Cream of the Crop 21

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / editor / auror300.zip / FUNCTION.DOX < prev next >

Wrap

Text File | 1996-07-17 | 381KB | 8,809 lines

The AML Function Reference ────────────────────────── This Function Reference documents all macro language Statements, Builtin functions, and Library functions for The Aurora Macro Language (AML). Several editor Extension functions are also documented. For a macro language tutorial, see the Language Reference. For information on how to install, configure, and use Aurora, see the Users Guide. To use the Function Reference within a macro: move the cursor to a function name or statement keyword and press <shift f2>. You can use <shift f2> in any document, including the Language Reference (Language.dox) and the Function Quick Reference (Quickfun.dox). You can also navigate through this document by moving the cursor to the 'see also' keywords and pressing <shift f2>. ────────────────────────────────────────────────────────────────────── Copyright (C) 1996 by nuText Systems. All rights reserved worldwide. No parts of this document may be copied in part or in whole, except as provided in the License in the accompanying documentation. ────────────────────────────────────────────────────────────────────── This document is divided into three sections: 1. Language Statements 2. Functions (builtin functions and library functions) 3. Events (builtin events) Topics are sorted alphabetically within each section. Statements are indicated by the label [Statement], library functions are indicates by [Lib], and extension functions are indicated by [Ext]. Builtin functions and events are not labeled. Each library function is also labeled with the object where it is defined. ┌─────────────────────────────────────────────────────────────────────┐ │ Language Statements │ └─────────────────────────────────────────────────────────────────────┘ break [Statement] ────────────────────────────────────────────────────────────────────── remarks: The 'break' statement will force an unconditional exit from 'for', 'loop', 'repeat', and 'while' loops. returns: nothing see also: loop, repeat, while example: loop keycode = getkey case keycode when <esc> // <esc> exits the loop break otherwise say "you pressed " + (geteventname keycode) end end case [Statement] ────────────────────────────────────────────────────────────────────── format: case case_expr when when_expr expressions when when_expr, when_expr, when_expr expressions : otherwise expressions end / endcase The 'otherwise' clause is optional. remarks: The 'case' statement evaluates 'case_expr', and then evaluates each 'when' expression in order, until one is found whose value is equal to the value of 'case_expr'. If a matching 'when' expression is found, the expressions associated with the 'when' statement are evaluated. Multiple 'when' expressions (separated by commas) may be specified within a single 'when' clause. If no matching 'when' expressions are found, then the 'otherwise' clause (if present) is evaluated. returns: The value of the last expression evaluated in the 'when' or 'otherwise' clause. see also: if, if? example: case value when 1 say "value is one" when 3, 7 say "value is three or seven" when "abc" + "d" say "value is abcd" otherwise say "value is " + value end value = case value when 1 "one" when 2 "two" otherwise "undefined" end constant [Statement] ────────────────────────────────────────────────────────────────────── format: constant identifier = expression [, constant ...] constant function : end / endfunction remarks: This statment defines symbolic constants or compile-time functions. 'expression' is evaluated at compile-time without generating any object code. The lifetime of all constants is limited to the macro language compilation process. The 'constant function' statement defines functions which are called at compile-time to return constant values. Commas may be used to define multiple constants in one constant statement. The 'const' keyword is a synonym for 'constant'. returns: nothing see also: #exec, forward, function, include, variable example: constant five = 5 constant six = 2 * 3 msgbox five * six // displays '30' databuf [Statement] ────────────────────────────────────────────────────────────────────── format: databuf buffer : end / enddatabuf remarks: This statement creates a new buffer and initializes the buffer with data or adds data to the end of an existing buffer. 'buffer' specifies the bufferid. Each expression listed within the databuf-end group becomes a separate line in the buffer. At least one line is required. This statement is generally used to define an 'inline' data buffer in a macro, without requiring a separate file to be loaded. returns: nothing see also: createbbuf, createbuf, destroybuf example: databuf "abc" // bufferid 'abc' "first line" // 1st line x + 5 - y // 2rd line y // 3th line "a string" // 4th line end event [Statement] ────────────────────────────────────────────────────────────────────── format: event <key or event> (arg1 arg2 ...) : end / endevent The 'end' keyword is not required if this statement is followed by another 'event', 'key' or 'function' statement. remarks: This statement defines an event handling function in the current object with the event name: <key or event>. Evaluation and arguments are handled in the same way as the 'function' statement (see the 'function' statement). For all events generated by the editor except <char>, an eventcode is passed as the first argument. The <char> event handling function is passed the Ascii character entered as the first argument, and the eventcode as the second argument. returns: nothing see also: arg, forward, function, key example: key <ctrl c> (keycode) say "you pressed <ctrl c>, keycode=" + keycode end #exec [Statement] ────────────────────────────────────────────────────────────────────── format: #exec : #endexec remarks: This statement defines a section of macro code which is executed at compile-time. No object code is generated for any expressions contained within the #exec-#execend group. Any functions defined within the #exec block are evaluated at compile time when called. Public object variables which are assigned values within the #exec block group are treated as constants when referenced outside the #exec block. returns: nothing see also: constant, forward, function, include, set, variable for [Statement] ────────────────────────────────────────────────────────────────────── format: for variable = start to/downto limit [ step/by expr ] do expressions end / endfor The keywords 'step' and 'by' are optional. The keyword 'do' is also optional, but may make the statement easier to read. remarks: The 'for' statement evaluates 'expressions' repeatedly, assigning a new value to 'variable' for each iteration of the loop. The value of the 'start' expression is initially assigned to 'variable' and the loop terminates when the value of the 'limit' expression has been exceeded. 'limit' is tested before the first iteration of the loop. Both the 'start' and 'limit' expressions are evaluated only once at the first iteration of the loop. If the keyword 'to' is specified, the variable is incremented for each iteration of the loop, otherwise the variable is decremented. If the keyword 'step' is specified, the 'step' expression defines a fixed value by which the loop variable is incremented or decremented. If the keyword 'by' is specified, the value of the 'by' expression is assigned to the loop variable at each iteration. No scalar comparsion (less than or greater than) is performed at each loop iteration when 'by' is specified. The 'break' or 'return' statements can be used to force an exit from the loop. returns: nothing see also: break, loop, repeat, return, while forward [function/object] identifier [Statement] ────────────────────────────────────────────────────────────────────── remarks: This keyword defines the specified identifier as a function name or an object name. If the function or object keyword is not specified, then 'function' is assumed. If a function or object is referenced before it is defined, then the 'forward' keyword must be used to inform the compiler that the identifier is a function name or an object name. returns: nothing see also: function, key, variable function [Statement] ────────────────────────────────────────────────────────────────────── format: function functionname (arg1 arg2 ...) : end / endfunction The 'end' keyword is not required if this statement is followed by another 'function', 'event', or 'key' statement. remarks: This statement defines a function in the current object with the name 'functionname'. Expressions contained within the function definition will be evaluated when the function is called. Function arguments can be referenced as variables within the function by listing them within parentheses after the function name. Note that arguments can also be referenced with the 'arg' function (see the 'arg' function). returns: nothing see also: arg, event, forward, key, setfunction example: function hello (name) say "Hello " + name + '!' end #if [Statement] ────────────────────────────────────────────────────────────────────── format: #if if_expr source code #elseif elseif_expr source code : #else source code #end / #endif The '#elseif' and '#else' clauses are optional. remarks: This statement is evaluated at compile-time. The expression 'if_expr' is evaluated. If TRUE, then the source code in the #if clause is compiled. If not TRUE, then the expression 'elseif_expr' is evaluated. If 'elseif_expr' is TRUE, then the source code in the #elseif clause is compiled, otherwise the source code in the '#else' clause (if present) is compiled. Multiple '#elseif' clauses may be specified. returns: nothing see also: constant, #exec if [Statement] ────────────────────────────────────────────────────────────────────── format: if if_expr then expressions elseif elseif_expr then expressions : else expressions end / endif The 'elseif' and 'else' clauses are optional. The keyword 'then' is also optional, but may make the statement easier to read. remarks: The 'if' statement evaluates the expression 'if_expr'. If TRUE, then the expressions in the 'if' clause are evaluated. If not TRUE, then the expression 'elseif_expr' is evaluated. If 'elseif_expr' is TRUE, then the expressions in the 'elseif' clause are evaluated, otherwise the expressions in the 'else' clause (if present) are evaluated. Multiple 'elseif' clauses may be specified. returns: The value of the last expression evaluated in the 'if', 'elseif', or 'else' clauses. see also: case, if? if? if_expr then_expr else_expr [Statement] ────────────────────────────────────────────────────────────────────── remarks: The 'if?' statement is a shorter form of the 'if' statement (see the 'if' statement'). The keywords 'then', 'elseif', and 'else' are not used. The 'if?' statement is primarily intended for use within expressions, where it may be more convenient than the 'if' statement. returns: The value of 'then_expr' or 'else_expr'. see also: case, if example: string1 = if? a == 1 "a is one" "a is not one" include expression [Statement] ────────────────────────────────────────────────────────────────────── remarks: This statement includes the macro language file defined by 'expression' at the current source code location. The specified expression is always evaluated at compile time. Any user-defined variables or functions referenced within the expression must have been previously defined as constants or within an '#exec-#execend' group. This statement will include both macro source (.Aml) files and compiled macro (.X) files. returns: nothing see also: constant, #exec example: include "d:\\macros.aml" include drive + path + filename key [Statement] ────────────────────────────────────────────────────────────────────── format: key <key or event> (arg1 arg2 ...) : end / endkey The 'end' keyword is not required if this statement is followed by another 'key', 'event', or 'function' statement. remarks: This statement defines an keyboard event handling function in the current object with the event name: <key or event>. Evaluation and arguments are handled in the same way as the 'function' statement (see the 'function' statement). For all keyboard events generated by the editor except <char>, an eventcode is passed as the first argument. The <char> event handling function is passed the Ascii character entered as the first argument, and the eventcode as the second argument. returns: nothing see also: arg, event, forward, function, setfunction example: key <ctrl c> (keycode) say "you pressed <ctrl c>, keycode=" + keycode end keyword keyword1, keyword2, ... [Statement] ────────────────────────────────────────────────────────────────────── remarks: This statement inserts 'keyword1', 'keyword2', etc. as syntax highlighting keywords in the current (executing) object. The keywords must be separated by commas. Syntax highlighting keywords are stored as public object variables whose value is the keyword color. If the value is null, then the keyword color defined by the 'syntax' function is assumed. The 'keyword' statement always assigns a value of null to the object variable. returns: nothing see also: setsyntax, syntax example: see the configuration file Syntax.aml loop [Statement] ────────────────────────────────────────────────────────────────────── format: loop [ expression times ] expressions end / endloop remarks: The 'loop' statement evaluates 'expressions' repeatedly until a 'break' or 'return' statement is encountered. An optional 'times' expression may be specified to limit the number of iterations. returns: nothing see also: break, for, repeat, return, while menu [Statement] ────────────────────────────────────────────────────────────────────── format: menu menuname item description1 expressions1 item description2 expressions2 : end / endmenu remarks: This statement creates a new menu buffer with the bufferid 'menuname'. 'description1', 'description2', etc. are the text strings associated with each item on the menu. Each description may contain one ampersand character (&) indicating that the character following it is to be highlighted. 'expressions1', 'expressions2', etc. are macro expressions to be associated with the menu items. These expressions can be retrieved and evaluated when a menu item is selected (see the 'getmenu' function). returns: The new menu bufferid if successful, otherwise null. see also: asciibuf, createbbuf, destroybuf, loadbuf, menubar, popup example: menu "Colors" item "&Red" say "you selected red" item "&Green" say "you selected green" item "&Blue" say "you selected blue" end menubar [Statement] ────────────────────────────────────────────────────────────────────── format: menubar window bar[1-4] item description1 expressions1 item description2 expressions2 : end / endmenubar remarks: This statement creates or changes a menu bar for a window. If 'window' is null, then the current window is assumed. 'description1', 'description2', etc. are the text strings associated with each item on the menu bar. Each description may contain one ampersand character (&) indicating that the character following it is to be highlighted. If a pair of ampersand characters (&&) is specified, the character is highlighted with the window title bar control color. 'expressions1', 'expressions2', etc. are macro expressions to be associated with the menu bar items. These expressions can be retrieved and evaluated when a menu bar item is selected (see the 'getmenubar' function). Up to four menu bars can be defined for one window. 'bar' specifies which of the four menu bars is being defined, and can be one of the following values: 1 - the primary menu bar at the top of the window, under the north title bar (if any) 2 - menu bar 2 directly underneath the primary menu bar 3 - menu bar 3 directly underneath menu bar 2 4 - menu bar 4 at the bottom of the window, above the south title bar (if any) If 'bar' is null, then 1 is assumed. returns: TRUE if successful, otherwise null. see also: getmenubar, menu example: menubar '' 1 // primary menu bar item "&Red" say "you selected red" item "&Green" say "you selected green" item "&Blue" say "you selected blue" end object [Statement] ────────────────────────────────────────────────────────────────────── format: object objectname ( parent1 parent2 ... ) The inheritance list (parent1 parent2 ...) is optional. remarks: This statement changes the current (executing) object to 'objectname'. If the object does not exist, then it is created. If the inheritance path (parent1 parent2 ...) is specified, then the object will inherit functions and object variables from the objects 'parent1', 'parent2', etc. If the object name 'entry' is specified from within an external macro, then the current object is changed back to what the current object was when the external macro was invoked. Note that the 'object' statement will also terminate (serve as an 'end' statement for) the 'function', 'event', or 'key' statements. returns: nothing see also: createobject, destroyobject, function, getcurrobj, inheritkeys, loadobject, object?, settype, setobjtype example: object abc // makes 'abc' the current object (and creates it // if it doesn't exist) object abc (def xyz) // makes 'abc' the current object (and creates it // if it doesn't exist). 'abc' will inherit // code and data from objects 'def' and 'xyz' ref variable [Statement] ────────────────────────────────────────────────────────────────────── remarks: The 'ref' keyword can be used to return more than one value from a function. When 'ref' is specified immediately before a local or global variable in a function call, it indicates that the variable is to be passed 'by reference' to the function. If the variable is modified in the called function, it is also modified where it was called. returns: nothing example: function modify (c d) c = 13 d = 14 end function callmod a = 1 b = 2 modify ref a ref b return a + b // returns 27 end repeat [Statement] ────────────────────────────────────────────────────────────────────── format: repeat expressions until until_expr remarks: The 'repeat' statement evaluates 'expressions' repeatedly until the value of the expression 'until_expr' is TRUE (not zero and not null). 'until_expr' is tested after the first iteration of the loop. The 'break' or 'return' statements can be used to force an exit from the loop. returns: null see also: break, for, loop, return, while example: variable i repeat // counts from 0 to 9 say "i is " + i delay 500 i = i + 1 until i == 10 return expression [Statement] ────────────────────────────────────────────────────────────────────── remarks: This statement returns the value of 'expression' immediately and unconditionally to the calling function. returns: the value of the specified expression. example: return "The value is: 13" // returns a string return 6 + 7 // returns 13 return // returns the null string variable identifier, [variable...] [Statement] ────────────────────────────────────────────────────────────────────── remarks: This keyword defines the specified identifier as a variable name, and initializes it to zero. If a variable is referenced in a statement before the statement in which it is assigned a value (and is not referenced in a function argument list), then this keyword must be used to inform the compiler that the specified identifier is a variable name. Commas may be used to define multiple variables in one variable statement. The keyword 'var' is a synonym for 'variable'. returns: nothing see also: forward example: function count (b) variable a while a < b do a = a + 1 end end while [Statement] ────────────────────────────────────────────────────────────────────── format: while while_expr do expressions end / endwhile The keyword 'do' is optional, but may make the statement easier to read. remarks: The 'while' statement evaluates 'expressions' repeatedly while the expression 'while_expr' is TRUE (not zero and not null). 'while_expr' is tested before the first iteration of the loop. The 'break' or 'return' statements can be used to force an exit from the loop. returns: null see also: break, for, loop, repeat, return ┌─────────────────────────────────────────────────────────────────────┐ │ Functions │ └─────────────────────────────────────────────────────────────────────┘ about [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays an about box with the editor version, and the date and time. returns: The button pressed (Ok), or null if nothing was pressed. actualcol apparentcolumn row buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the actual column for an apparent (visible) column in the specified line. If the row and buffer are not specified, the current line and buffer are assumed. The apparent and actual columns may differ if the line contains tab characters (Ascii 9) which are displayed as spaces (see 'setbuftabs'). returns: the actual column if successful, otherwise null. see also: apparentcol, getbuftabs, setbuftabs actualrow (+/-)lines row buffer ────────────────────────────────────────────────────────────────────── remarks: This function returns the actual line number which is the apparent distance on the screen of 'lines' lines away from the specified row. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: A line number if successful, otherwise null. see also: apparentrow, fold?, getfold example: actualrow -5 // returns the line number which appears to be 5 // lines above the current line on the screen addhistory historybuffer string [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds 'string' to the specified history buffer and makes it the most recently used history string. The history buffer is created if it does not exist. returns: nothing see also: askhistory, gethiststr, pophistory example: addhistory "_load" "c:\\file.txt" // adds c:\file.txt to the history buffer '_load' addhistory "_find" "apples" // adds 'apples' to the history buffer '_find' addline string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts a new line containing the specified string into a buffer. This function is almost identical to the 'insline' function, except that new lines are added to the end of the buffer if 'row' is not specified (see 'insline'). returns: TRUE if successful, otherwise null. see also: delline, insline, insabove, joinline, splitline example: addline // adds a new blank line to the end of the // current buffer addline "Last line" // adds a new line with the text 'Last line' // after the last line in the current buffer adjustcol col window ────────────────────────────────────────────────────────────────────── remarks: Scrolls a window left or right relative to the position of the cursor in the window. If 'window' is not specified, the current window is assumed. This function does not move the cursor in the buffer. The window is scrolled so that the cursor appears 'col' minus 1 columns from the left edge of the client area. If 'col' is not specified, the window is scrolled to a position that leaves the cursor in the horizontal center of the window. returns: nothing see also: adjustrow example: adjustcol // attempts to scroll the window so that the cursor // is horizontally centered in the window. adjustcol 3 // attempts to scroll the window so that the cursor // is 3 columns from the left edge of the window adjustrow row window ────────────────────────────────────────────────────────────────────── remarks: Scrolls a window up or down relative to the position of the cursor in the window. If 'window' is not specified, the current window is assumed. This function does not move the cursor in the buffer. The window is scrolled so that the cursor appears 'row' minus 1 lines from the top edge of the client area. If 'row' is not specified, the window is scrolled to a position that leaves the cursor in the vertical center of the window. returns: nothing see also: adjustcol example: adjustrow // attempts to scroll the window so that the cursor // is vertically centered in the window. adjustrow 3 // attempts to scroll the window so that the cursor // is 3 rows from the top edge of the window apparentcol actualcol row buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the apparent (visible) column for an actual column in the specified line. If the row and buffer are not specified, the current line and buffer are assumed. The apparent and actual columns may differ if the line contains tab characters (Ascii 9) which are displayed as spaces (see 'setbuftabs'). returns: the actual column if successful, otherwise null. see also: actualcol, getbuftabs, setbuftabs apparentrow (+/-)lines row buffer ────────────────────────────────────────────────────────────────────── remarks: This function returns the apparent line number on the screen which is the actual distance of 'lines' lines away from the specified row. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: A line number if successful, otherwise null. see also: actualrow, fold?, getfold example: apparentrow 5 // returns the apparent line number on the screen // of the line 5 lines below the current line arg n ────────────────────────────────────────────────────────────────────── remarks: Retrieves the 'nth' argument, or the number of arguments passed to the currently executing function. If 'n' is zero or not specified, then the number of arguments is returned, otherwise the 'nth' argument is returned. returns: A function argument or the number of function arguments. see also: function, key example: function abc say (arg) + " args passed, first is: " + (arg 1) end abc 1 2 3 // displays: '3 args passed, first is: 1' array size ────────────────────────────────────────────────────────────────────── remarks: Creates an array of 'size' elements, where each element in the array is initialized to the null string. 'size' cannot be greater than 2000. returns: an array see also: array? array? expression ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified expression is an array. returns: TRUE if the exression is an array, otherwise null. see also: array asciibuf buffer ────────────────────────────────────────────────────────────────────── remarks: This function creates a new buffer containing an Ascii chart with 256 lines - one for each Ascii character. The new buffer will become the current buffer. If 'buffer' is null or not specified, a unique bufferid will be assigned. Note: this function will not display the new buffer in a window. The 'popup' or 'openbuf' library functions should be used to display the buffer. returns: The new bufferid if successful, otherwise null. see also: asciibuf, createbbuf, destroybuf, loadbuf, menu, openbuf, popup ask prompt history init title opt=[c12d] width [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string. The following parameters may be specified: prompt - the prompt displayed to the user history - the history buffer to use in the prompt init - the initial value to place in the prompt title - the prompt title (dialog boxes only) width - the prompt width (dialog boxes only) The following prompt style options may also be specified: c - command line prompt 1 - one-line box prompt 2 - two-line box prompt d - dialog box prompt If no options are specified, the value of PromptStyle in Config.aml is used as the default prompt style. If a history bufferid is specified and does not already exist, then it is created. Note that entered strings are not automatically added to the history buffer (the 'addhistory' function must be used). returns: This function returns the string entered. If nothing is entered and the <enter> key is pressed, then one blank (Ascii 32) is returned. If the prompt is cancelled, then null is returned. see also: addhistory, okbox, pickfile, popup, yncbox example: ask "Enter a string" // prompts for a string ask "Enter a file name" "_load" "c:\\file.txt" // prompts for a string, initializing the prompt with // c:\file.txt. The "_load" history buffer is // available within the prompt ask "Enter a string" '' "initial string" "Enter" 'd' 20 // prompts for a string using a dialog box prompt of // width 20 with the title 'Enter". The prompt // is initialized with "initial string". askbox refvalue prompt history init [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string in a two-line box prompt. The following parameters may be specified: refvalue - the variable to hold the return string prompt - the prompt displayed to the user history - the history buffer to use in the prompt init - the initial value to place in the prompt If a history bufferid is specified and does not already exist, then it is created. Note that entered strings are not automatically added to the history buffer (the 'addhistory' function must be used). returns: TRUE if a string was entered, or null if the prompt was cancelled. The user string is returned in the variable 'refvalue' (passed by reference). see also: addhistory, ask, askbox1, askline example: variable value // prompt for a string if askbox ref value "File name?" _load "File.txt" then // user string is returned in 'value' msgbox "You entered " + value end askbox1 refvalue prompt history init [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string in a one-line box prompt. The parameters and return values are identical to the 'askbox' function. returns: see askbox. see also: ask, askbox, askline askhistory [Lib][prompt] ────────────────────────────────────────────────────────────────────── remarks: Displays a history popup menu for the current prompt. If a string is selected, it is entered automatically into the prompt. This function is only for use within prompts. returns: The string selected from the popup menu, or null if nothing was selected or the history buffer does not exist. see also: pophistory askline refvalue prompt history init [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Prompts the user to enter a string in a command-line prompt. The parameters and return values are identical to the 'askbox' function. returns: see askbox. see also: ask, askbox, askbox1 assignkey [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Assigns the current scrap key macro to a key. The user is prompted to enter the key. If the key macro is assigned, the scrap macro is erased. Note: key macros cannot be assigned to multi-keys with this function. returns: nothing see also: assignkey, openkey, playing?, savekey, setting base number newbase ────────────────────────────────────────────────────────────────────── remarks: Converts a decimal or hexadecimal number to a string representing a number of any base from 2 to 36. returns: a string representing the number in base 'newbase'. see also: bin2hex, hex2bin example: base 45 16 // returns "2D" base 45 8 // returns "55" base 45 2 // returns "101101" beep frequency milliseconds ────────────────────────────────────────────────────────────────────── remarks: Beeps the PC speaker at the specified frequency (in Hz) for the specified number of milliseconds. If 'milliseconds' is omitted, the speaker will sound indefinitely until the next call to this function. If no arguments are passed to this function, then the speaker is turned off. returns: nothing see also: delay example: beep 500 1000 // beeps at 500Hz for 1 second beep 800 // beeps at 800Hz indefinitely beep // turns sound off begdesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Clears the current desktop and marks the beginning of a series of window 'close' calls which add each closed window to the current desktop. This would typically be used for exiting the editor and saving all open windows as the current desktop. returns: nothing see also: close, enddesk bin2hex binarystring ────────────────────────────────────────────────────────────────────── remarks: Converts a binary string into a string representing its hexadecimal value returns: a hexadecimal string. see also: hex2bin example: bin2hex 'a' // returns "61" bin2hex 'abc' // returns "616263" bin2int binarystring ────────────────────────────────────────────────────────────────────── remarks: Converts 1, 2, or 4 byte binary strings into integers. returns: an integer. see also: char, char2, char4 example: bin2int 'a' // returns 97 bin2int 'ab' // returns 25185 bin2int 'abcd' // returns 1684234849 blink [0/1] ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) the video blink mode. Disabling the video blink mode allows the brighter background colors (128-255) to be used. returns: nothing see also: display book? bookmark ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified bookmark exists. returns: TRUE if the bookmark exists, otherwise null. see also: setbook bootpath filename ────────────────────────────────────────────────────────────────────── remarks: Converts an unqualified or partially qualified filename into a fully-qualified filename based on the editor 'bootpath' (the location of the main editor .Exe file). returns: a fully qualified filename or directory specification. see also: getbootpath, qualify example: bootpath "kbd.aml" // returns c:\aurora\kbd.aml if 'c:\aurora' is the // editor bootpath break? ────────────────────────────────────────────────────────────────────── remarks: Tests if <ctrl break> was pressed. returns: TRUE if <ctrl break> was pressed, otherwise null. see also: breakoff breakoff ────────────────────────────────────────────────────────────────────── remarks: Clears the break flag that was turned on by pressing the <ctrl break> key. Calling this function will stop <ctrl break> from exiting loops and beeps. returns: nothing see also: break? bufchanged? buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if a buffer is modified by checking the buffer 'modified' flag. If 'buffer' is null or not specified, the current buffer is assumed. returns: non-zero if the buffer is modified, otherwise null. see also: bufferflag buffer? buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if a buffer exists. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if the buffer exists, otherwise null. see also: bufferflag bufferflag opt=[-+?cdhmprt] buffer ────────────────────────────────────────────────────────────────────── remarks: Turns buffer flags on or off, or tests if a buffer flag is turned on. If 'buffer' is null or not specified, the current buffer is assumed. The following flags can be specified: c - clear all 'dirty' or modified lines (set only) d - directory buffer (query only) This flag can be used to test if a buffer was initially loaded as a directory. h - hidden buffer This flag can be used to hide a buffer from the 'getprevbuf' function. This will effectively prevent temporary or internal buffers from being displayed on editor buffer lists. m - buffer 'modified' flag p - process 'dirty' or modified lines r - buffer read/only (protected) flag t - truncated buffer (query only) This flag can be used to test if the specified buffer has been truncated when loaded. Truncation can occur if <ctrl break> was pressed while loading the file. - - turn specified flags off + - turn specified flags on ? - return true if specified flags are on If flags are specified without -, +, or ?, then they will be turned on and any other flags not specified will be turned off. returns: TRUE if '?' is specified with flags that are on, otherwise null see also: bufchanged?, lineflag example: bufferflag "-m" // turn off the buffer-modified flag bufferflag "c" // clear all modified lines bufferflag "r" // make current buffer read/only button title x y width height [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds a button window control to the current dialog box. The button window becomes the current window. The following parameters may be specified: title - the button title x - the button x-position in the dialog box y - the button y-position in the dialog box width - the button width (if not specified, the button is sized to accomodate the title) height - the button heigth (if not specified, the button height is 1) returns: The button window id. see also: field, dialog, groupbox, listbox, whenenter example: dialog "Test Dialog Box" 40 5 // create a dialog box button "O&k" 18 2 8 // add a button getdialog // display the dialog box button? buttonmask ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified mouse button(s) are currently pressed down. 'buttonmask' can be any combination of the following values bitwise-ORed together: 01h - left button is down 02h - right button is down 04h - center button is down If 'buttonmask' is not specified, then 07h is assumed. returns: Non-zero if the specified button keys are down, otherwise zero. example: button? // test if any mouse buttons are down button? 2 // test if the right mouse button is down call funexpression arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls a function in the current object whose name is the value of 'funexpression', passing the arguments 'arg1', 'arg2', etc. returns: The return value of 'funexpression'. see also: eval, pass, send, sendobject example: call "beep" 400 400 call "be" + "ep" 400 400 cascade [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Cascades all non-minimized windows on the screen. returns: nothing see also: splitwin, tile caseblock opt=[lu] mark ────────────────────────────────────────────────────────────────────── remarks: Changes the case of marked text. If 'mark' is not specified, then the default markid is assumed. Any combination of the following options may be specified: l - change text to lower case u - change text to upper case If options 'l' and 'u' are both specified, the case of each character in the mark is toggled. If no options are specified, then 'u' is assumed. returns: TRUE if successful, otherwise null. see also: flipcase, locase, upcase char number1 number2 ... ────────────────────────────────────────────────────────────────────── remarks: Converts its numeric arguments to one byte character strings whose Ascii value is the numeric argument. returns: The concatenated string of all arguments converted to one byte strings. see also: bin2int, char2, char4 example: char 97 // returns "a" char 65 66 67 // returns "ABC" char2 number1 number2 ... ────────────────────────────────────────────────────────────────────── remarks: Converts its numeric arguments to two byte binary character strings. returns: The concatenated string of all arguments converted to two byte strings. see also: bin2int, char, char4 example: char2 6261h // returns "ab" char4 number1 number2 ... ────────────────────────────────────────────────────────────────────── remarks: Converts its numeric arguments to four byte binary character strings. returns: The concatenated string of all arguments converted to four byte strings. see also: bin2int, char, char2 example: char4 64636261h // returns "abcd" close opt=[s] [Lib][win,edit_fmgr,prompt] [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: Closes the current window. If the buffer in the window is not displayed in any other windows, the buffer is also destroyed. If option 's' is specified and the window is an edit window, the file is saved. returns: nothing see also: open, save, setname example: close // closes the current window close 's' // saves the current buffer and closes the current // window closefile handle ────────────────────────────────────────────────────────────────────── remarks: Closes a file handle opened with 'openfile'. If a file handle is not specified, then the file handle returned from the most recent openfile call is assumed. returns: nothing see also: filepos, openfile, readfile, writefile closefold opt=[s] row buffer ────────────────────────────────────────────────────────────────────── remarks: Closes the open fold spanning the specified row. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 's' is specified, all open subfolds within the fold are also closed. returns: the number of folds closed see also: createfold, destroyfold, foldblock, getfold, openfold example: closefold // closes the open fold spanning the current line in // the current buffer, leaving any subfolds open closemouse ────────────────────────────────────────────────────────────────────── remarks: Deactivates the mouse driver and removes the mouse pointer from the screen. When this function is called, mouse events will no longer be processed by the event queue. returns: nothing see also: openmouse col col buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified column, but does not change the row. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor column if successful, otherwise null. see also: gotopos, row example: col 1 // moves the cursor to column 1 of the current line // in the current buffer col getlinelen + 1 // moves the cursor one column past the end of the // current line in the current buffer colorcursor color cursor ────────────────────────────────────────────────────────────────────── remarks: Changes the color of a cursor to the attribute 'color'. If 'cursor' is not specified, the current 'cursor' in the current buffer is assumed. If the color -1 is specified, the default window mark color is used. If the color -2 is specified, the cursor is hidden. returns: TRUE if successful, otherwise null. see also: colormark, getcolor, getcurrcurs, setcolor example: colorcursor 95 // changes the color of the current cursor to // white on magenta colormark color mark ────────────────────────────────────────────────────────────────────── remarks: Changes the mark color to the attribute 'color'. If this function is not used, the window mark color is assumed. This function allows individual marks to have different colors. If 'mark' is not specified, the default markid is assumed. If the color -1 is specified, the default window mark color is used. If the color -2 is specified, the mark is hidden. returns: TRUE if successful, otherwise null. see also: colorcursor, getcolor, setcolor example: colormark 95 // changes the color of the current mark to // white on magenta compilemacro sourcefile destfile ────────────────────────────────────────────────────────────────────── remarks: Compiles the macro source file 'sourcefile' and places the object code in the file 'destfile'. Error information can be retrieved with the 'geterror' function. returns: Null if the compilation was successful, otherwise one of the following compiler error codes: 1001 - can't open file 1002, 1003 - read error 1004 - not an executable macro file 1031 - write error 1032 - can't open compiler output file 1101 - no closing quote 1102 - no closing bracket 1103 - invalid symbol 1104 - invalid key or event 1301 - no terminator 1302 - unexpected end of source 1303 - no closing parenthesis 1310 - unexpected argument 1311 - unexpected terminator 1312 - unexpected function 1313 - unexpected operator 1314 - unexpected keyword 1315 - invalid redefinition 1318 - invalid number 1319 - identifier not defined (the identifier name can be retrieved with the 'geterror' function, using option 's') 1320 - bad assignment 1330 - bad when clause 1336 - improperly placed break 1337 - invalid reference 1501 - can't open include file (the include file name can be retrieved with the 'geterror' function, option 's') 1502 - include level exceeded 1504 - statement must be at top level 1507 - can't redefine builtin function 1508 - duplicated function argument 1701 - too many variables 1703 - function or expression too large 1704, 1705, 1707, 1708 - internal stack overflow 1706 - out of symbol space any other code - fatal compilation error see also: eval, geterror, runmacro, seterror example: compilemacro "c:\\aurora\\macro\\utility.aml" "c:\\aurora\\macro\\utility.x" concat string1 string2 ... ────────────────────────────────────────────────────────────────────── remarks: Concatenates all of its arguments. All arguments may be numeric. The concatenation operator (+) may also be used to concatenate strings, but at least one operand must be non-numeric. returns: the concatenated string of all the arguments. see also: copystr example: concat "Red" "Green" "Blue" // returns "RedGreenBlue" concat 1 2 3 // returns "123" copyblock mark buffer col row ────────────────────────────────────────────────────────────────────── remarks: Copies marked text after the position 'col','row' in the specified buffer. The text is inserted at the new position and the mark is also moved to the new position. If 'mark' is not specified, the default markid is assumed. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: copyblockover, moveblock copyblockover mark buffer col row ────────────────────────────────────────────────────────────────────── remarks: Copies marked text to 'col','row' in the specified buffer. The text is overlaid at the new position (not inserted) and the mark is moved to the new location. If 'mark' is not specified, the default markid is assumed. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: copyblock, moveblock copyfile sourcefile destfile opt=[au] ────────────────────────────────────────────────────────────────────── remarks: Copies the file 'sourcefile' to 'destfile'. Any of the following options can be specified: a - append the sourcefile to the destination file u - update the destination file date/time returns: Non-zero if successful, otherwise zero. see also: deletefile, renamefile copymark oldmark newmark ────────────────────────────────────────────────────────────────────── remarks: Creates a new mark with the markid 'newmark' by making a copy of 'oldmark'. If 'newmark' is not specified, a unique markid will be assigned. The new mark will reside in the same buffer as 'oldmark' and have the same size and type. The new mark becomes the current mark for the buffer. returns: TRUE if successful, otherwise null. see also: markchar, markcolumn, markline, markstream example: copymark '*' 'T' // create a temporary copy of a mark : destroymark 'T' // destroy the temporary mark copystr string count ────────────────────────────────────────────────────────────────────── remarks: Concatenates a string with itself for 'count' number of times. returns: the argument string copied 'count' times. see also: concat example: copystr "Red" 4 // returns "RedRedRedRed" copywin [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Copies the current edit window. The new edit window will display the same file in memory as the original window. returns: TRUE if successful, otherwise null. see also: splitwin createbuf buffer line1 line2 ... ────────────────────────────────────────────────────────────────────── remarks: This function creates a new buffer with the specified bufferid. If the bufferid is already in use, this function will fail. If 'buffer' is null or not specified, a unique bufferid will be assigned. The new buffer will become the current buffer. Initial lines can be placed in the buffer with the arguments 'line1', 'line2', etc. If no lines are specified, one blank line is assumed. Note: this function will not display the new buffer in a window. The 'openbuf' library function should be used to display the buffer. returns: The new bufferid if successful, otherwise null. see also: asciibuf, buffer?, createbbuf, destroybuf, loadbuf, menu, openbuf example: createbuf // creates a new buffer and returns a // unique bufferid createbuf "abc" // creates new buffer with the // bufferid "abc" createbuf '' // creates a new buffer with 2 lines "First Line" // and returns a unique bufferid "Second Line" createbbuf buffer line1 line2 ... ────────────────────────────────────────────────────────────────────── remarks: This function creates a new binary buffer with the bufferid 'buffer'. By default, when a binary buffer is saved, line delimiter characters are not appended to the end of each line. This function is almost identical to the 'createbuf' function, except that a binary buffer is created (see 'createbuf'). returns: The new bufferid if successful, otherwise null. see also: asciibuf, buffer?, createbuf, destroybuf, loadbuf, menu createcursor cursor buffer ────────────────────────────────────────────────────────────────────── remarks: This function creates a new cursor. If the specified cursor already exists, this function will fail. If 'cursor' is null or not specified, a unique cursorid will be assigned. If 'buffer' is null or not specified, the current buffer is assumed. The new cursor will become the current cursor for the buffer. returns: Non-zero if successful, otherwise zero. see also: cursor?, destroycursor, setcursor createdir path ────────────────────────────────────────────────────────────────────── remarks: Creates a new directory specified by 'path'. Only one directory in the path can be created at a time. returns: Non-zero if successful, otherwise zero. see also: directory?, file?, locatefile createfold opt=[c] row buffer ────────────────────────────────────────────────────────────────────── remarks: Creates a one-line text fold. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 'c' is specified, the fold is created 'closed', otherwise the fold is created 'open'. returns: non-zero if successful, otherwise null. see also: closefold, destroyfold, foldblock, foldline, getfold, openfold example: createfold // creates an open fold on the current line in // the current buffer createobject object parent1 parent2 ... ────────────────────────────────────────────────────────────────────── remarks: Creates a new object. If 'object' is not specified, a unique object name will be assigned. If the inheritance path 'parent1 parent2 ...' is specified, then the object will inherit public functions and object variables from the objects 'parent1', 'parent2', etc. This function can be used to create objects dynamically. Unlike the 'object' statement, this function does not modify the current object. returns: the new objectid if successful, otherwise null. see also: destroyobject, loadobject, object, object?, setobjtype createwindow window ────────────────────────────────────────────────────────────────────── remarks: Creates a new window. If 'window' is null or not specified, a unique windowid will be assigned. The new window will become the current window. The new window will be sized to cover the entire physical screen and will not have any borders or frame controls. To add frame controls to the window, see the 'setframe' function. To change the border size and style, see the 'setborder' function. The window event object will be set to the current (executing) object. To change the window event object, see the 'setwinobj' function. This function can be used to create simple video output windows, or windows that display buffers. returns: The new windowid if successful, otherwise null. see also: destroywindow, setwinobj, window? example: createwindow // create a new window setframe "b" // add borders setborder "1i" // set the border style setcolor 0 127 // set border color setcolor 5 112 // set text color settitle "Hello World!" // set window title sizewindow 6 5 72 20 "ad" // size the window setshadow 2 1 // add shadows to the window currbook bookmark ────────────────────────────────────────────────────────────────────── remarks: Makes the specified bookmark the current bookmark by moving it to the top of the bookmark list in the current buffer. returns: TRUE if successful, otherwise null. see also: getcurrbook currbuf buffer ────────────────────────────────────────────────────────────────────── remarks: Makes the specified buffer the current buffer by moving it to the top of the buffer list. returns: nothing see also: getcurrbuf, gotobuf currcursor cursor ────────────────────────────────────────────────────────────────────── remarks: Makes the specified cursor the current cursor by moving it to the top of the cursor list in the current buffer. returns: TRUE if successful, otherwise null. see also: getcurrcurs currdesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Sets the 'current' desktop to the current window layout on the screen. The current desktop can be restored later with the 'restoredesk' function, or saved to a file with the 'savedesk' function. returns: nothing see also: begdesk, enddesk, opendesk, openhistory, restoredesk, savedesk currmark mark ────────────────────────────────────────────────────────────────────── remarks: Makes the specified mark the current mark by moving it to the top of the mark list in the current buffer. Marks at the top of the mark list have higher priority when displayed on the screen. returns: TRUE if successful, otherwise null. see also: getcurrmark currpath path ────────────────────────────────────────────────────────────────────── remarks: Changes the current Dos path to 'path' for the disk drive specified in 'path'. returns: Non-zero if successful, otherwise zero. see also: getcurrpath example: currpath "d:\\abc" // changes the current path for the D drive to 'abc' currwin window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Brings the specified window to the top of the screen and makes it the current window. returns: nothing see also: getcurrwin cursor? cursor ────────────────────────────────────────────────────────────────────── remarks: Tests if a cursor exists. If 'cursor' is null or not specified, then the current cursor for the current buffer is assumed. returns: TRUE if the cursor exists, otherwise null. see also: createcursor, cursor?, destroycursor, setcursor cursorsize overtop overbot instop insbot ────────────────────────────────────────────────────────────────────── remarks: Sets the physical cursor size for insert and overstrike modes in windows which display a buffer. 'overtop' and 'overbot' specify the cursor top and bottom in overstrike mode. 'instop' and 'insbot' specify the cursor top and bottom in insert mode. The cursor top and bottom must be numbers from 0 to 99 and indicate the distance of the top and bottom of the cursor from the top of the character cell, on a scale of 0 to 99. returns: nothing see also: hidecursor, showcursor defext filename extension [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Appends the default extension 'extension' to the specified filename if the filename has no extension. returns: a filename with the default extension. see also: forceext example: defext "file" "doc" // returns 'file.doc' defext "file.txt" "doc" // returns 'file.txt' defext "file." "doc" // returns 'file.' delay milliseconds ────────────────────────────────────────────────────────────────────── remarks: Suspends execution of the editor for the specified number of milliseconds. returns: nothing see also: beep, halt, system example: delay 1000 // delay for 1 second delchar count col row buffer ────────────────────────────────────────────────────────────────────── remarks: Deletes text on a line in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. The text at the specified 'col' and 'row' are deleted. If 'col' are 'row' are not specified, the text at the cursor is deleted. 'count' specifies the number of characters to delete. If 'count' is not specified, 1 is assumed. returns: TRUE if successful, otherwise null. see also: instext, ovltext, text example: delchar // deletes the character at the cursor in the // current buffer delchar 4 // deletes 4 characters at the cursor in the // current buffer delchar 1 5 20 "abc" // deletes the character at column 5, line 20 // in the buffer "abc" deleteblock mark ────────────────────────────────────────────────────────────────────── remarks: Deletes marked text and destroys the mark. If 'mark' is not specified, the default markid is assumed. returns: TRUE if successful, otherwise null. see also: copyblock deletefile filename ────────────────────────────────────────────────────────────────────── remarks: Deletes the specified filename. 'filename' may also specify an empty directory. returns: TRUE if successful, otherwise null. see also: copyfile, renamefile deletewin [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Deletes the current window. For edit windows, the buffer in the window is not destroyed. returns: nothing see also: close delline count row buffer ────────────────────────────────────────────────────────────────────── remarks: Deletes a line or lines in a buffer. If 'buffer' is null or not specified, the current buffer is assumed. If 'row' is specified, lines are deleted starting with 'row', otherwise lines are deleted at the cursor. 'count' specifies the number of lines to delete. If 'count' is not specified, 1 is assumed. returns: the line number of the line deleted if successful, otherwise null. see also: addline, insabove, insline, joinline, splitline example: delline // deletes the line at cursor in the current buffer delline 4 // deletes the line at cursor and 3 lines below // it in the current buffer delline 1 1 "abc" // deletes the first line in the buffer "abc" if delline > getrow then // deletes the current line and tests if it was the // last line : end destroybook bookmark ────────────────────────────────────────────────────────────────────── remarks: Destroys a bookmark created with the 'setbook' function. If 'bookmark' is not specified, the current bookmark is assumed. returns: TRUE if successful, otherwise null. see also: setbook destroybuf buffer ────────────────────────────────────────────────────────────────────── remarks: Destroys a buffer, If 'buffer' is null or not specified, then the current buffer is destroyed. All windows, cursors, bookmarks, and marks associated with the buffer will also be destroyed. The previous buffer in the buffer list will become the current buffer. returns: nothing see also: createbbuf, createbuf, loadbuf destroycursor cursor ────────────────────────────────────────────────────────────────────── remarks: Destroys the specified cursor, and any window in which the cursor is displayed. If 'cursor' is not specified, then the current cursor in the current buffer is destroyed. If the buffer contains more than one cursor, the next cursor in the cursor list will become the current cursor. returns: TRUE if successful, otherwise null. see also: getcurswin, setcursor destroyfold opt=[s] row buffer ────────────────────────────────────────────────────────────────────── remarks: Destroys a closed fold. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 's' is specified, all closed subfolds within the fold are also destroyed. returns: the number of folds destroyed see also: closefold, createfold, foldblock, foldline, getfold, openfold example: destroyfold // destroys the closed fold at the current line in the // current buffer, leaving subfolds intact destroymark mark ────────────────────────────────────────────────────────────────────── remarks: Destroys a mark created with the markline, markcolumn, markchar, markstream, or copymark functions. The text within the mark is not affected. If 'mark' is not specified, the default markid is assumed. returns: TRUE if successful, otherwise null. see also: copymark, markchar, markcolumn, markline, markstream destroyobject object ────────────────────────────────────────────────────────────────────── remarks: Destroys the specified object. If 'object' is not specified, the current object is assumed. If possible, the object is destroyed immediately, otherwise the object will be destroyed when it is no longer referenced. returns: TRUE if the object is destroyed immediately, otherwise null. see also: createobject, loadobject, object, object?, resident, runmacro destroytimer timerid ────────────────────────────────────────────────────────────────────── remarks: Stops and destroys the timer identified by 'timerid'. This function will destroy both interval and alarm timers. returns: nothing see also: setalarm, settimer, timer? destroyvar variable object ────────────────────────────────────────────────────────────────────── remarks: Destroys the public object variable defined by 'variable' in the specified object. If 'object' is not specified, then the current object is assumed. returns: nothing see also: function?, lookup, set, variable? example: destroyvar "TempVar" destroyvar "Temp" + "Var" "edit" destroywindow window ────────────────────────────────────────────────────────────────────── remarks: Destroys a window and removes it from the screen. If 'window' is null or not specified, then the current window is destroyed. Any child windows of 'window' are also destroyed. The previous window in the window list will become the current window. returns: nothing see also: createwindow, window? dialog title width height opt=[cp] object [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Creates a main dialog box window to which dialog box controls may be added. The new dialog box becomes the current window and the 'current' dialog box. The following parameters may be specified: title - the dialog box title width - the dialog box width height - the dialog box height object - the name of an object to be notified when dialog box events occur The following options may also be specified: c - center the dialog box title (if this option is not specified, the title is left-justified) p - remember the dialog box position after closing (if this option is not specified, the dialog box will be centered) returns: The dialog box window id. see also: button, field, getdialog, groupbox, listbox, showdialog example: dialog "Test Dialog Box" 40 5 // create a dialog box getdialog // display the dialog box dir? filespec [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tests if 'filespec' specifies a directory. returns: TRUE if filespec specifies a directory, otherwise null. example: dir? "file.txt" // returns null dir? "*.txt" // returns true dir? "c:" // returns true directory? directory path ────────────────────────────────────────────────────────────────────── remarks: Tests for the existence of a directory in the specified path. This function is identical to the locatefile function when option 'd' is specified (see 'locatefile'). returns: The fully qualified directory if found, otherwise null. see also: file?, locatefile dispatch ────────────────────────────────────────────────────────────────────── remarks: This function reads the next event from the event queue and 'dispatches' it by calling a user-defined event handling function associated with the event. If no events are on the queue, this function waits for an event to appear on the queue. returns: TRUE if the 'endprocess' function was not called in the user event-handling function, otherwise null. see also: endprocess, process display opt=[f] ────────────────────────────────────────────────────────────────────── remarks: Updates the display. Any windows, buffers, and marks, and cursors which have been modified are redrawn. Specifying option 'f' forces the entire display to be redrawn (the background, all windows, etc.), even if nothing has been modified within the editor. This can be used to restore the display after another program, utility, or Dos command has overwritten it. returns: TRUE if the display was updated, otherwise null. see also: setdisplay down rows buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor downward. 'rows' specifies the number of lines to move. If 'rows' is not specified, 1 is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor line number if successful, otherwise null. see also: left, right, up example: down // moves the cursor down 1 row down 5 // moves the cursor down 5 rows enddesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Marks the end of a series of window 'close' calls which add the closed window to the current desktop. returns: nothing see also: begdesk endprocess ────────────────────────────────────────────────────────────────────── remarks: Posts a special internal 'quit' event to the event queue. When the editor processes this event, the current editor 'process' is terminated, and the editor returns to the previous process (or to Dos if there is no previous process). The internal 'quit' event forces the 'dispatch' function to return null, and the 'process' function call to return. returns: TRUE if successful, otherwise null. see also: dispatch, process eotstring titleid window ────────────────────────────────────────────────────────────────────── remarks: Sets the end-of-text line for a window which displays a buffer to a window title previously set with the 'settitle' function. If 'window' is not specified, the current window is assumed. 'titleid' specifies which one of the 5 window titles should be used. The title should be hidden with settitle option 'z' (see 'settitle'). If 'titleid' is not specified, then the end-of-text line is removed. If 'titleid' is -1, then the end-of-text line defaults to: "≡≡≡≡≡≡ End of Text ≡≡≡≡≡≡". returns: nothing see also: gettitle, settitle example: eotstring // removes the end-of-text line in the current window eotstring -1 // sets the end-of-text line to // '≡≡≡≡≡≡ End of Text ≡≡≡≡≡≡' erasekey opt=[a] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Erases the current scrap key macro. If option 'a' is specified, all current key macros are erased. returns: TRUE if successful, otherwise null. see also: openkey, playkey, savekey, setting eval string object ────────────────────────────────────────────────────────────────────── remarks: Compiles and evaluates a macro language source code string in the specified object. If 'object' is not specified, the current object is assumed. This function can also evaluate compiled expressions. Note that local and global variables defined outside of the scope of the eval string are not accessible from within the 'eval' function. returns: The result of evaluating the macro source string. The 'geterror' function can also be called to return an error code. The error code is zero if the string compiled successfully. see also: compilemacro, geterror, runmacro example: eval "beep 700 300" // beeps the speaker a = 40 x = eval '3 + ' + a [1] // x is '7' event? ────────────────────────────────────────────────────────────────────── remarks: Test if one or more events are currently in the event queue, including keyboard, mouse, and user-defined events. returns: TRUE if an event is in the queue, otherwise null. see also: geteventcount, keyhit?, shiftkey? extendmark col row mark ────────────────────────────────────────────────────────────────────── remarks: Extends a mark to the position defined by 'col','row'. If 'col' and 'row' are not specified then the current cursor position is assumed. If 'mark' is not specified, the default markid is assumed. returns: nothing see also: markchar, markcolumn, markline, markstream, stopmark fbreak [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Breaks out of the current 'fcommand' call. returns: nothing see also: fcommand fcommand function arg1 arg2 ... [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Calls the specified function once for each marked file in the current file manager window. If no files are marked, the function is called only once for the file or directory at the current line in the file manager. The function is called in the current event object. The fully qualified file name and the arguments 'arg1', 'arg2', etc. are passed to the function in following order: filename arg1 arg2 ... returns: nothing see also: fbreak, fmark, fmark? example: fcommand "setfileattr" attribute // calls the function 'setfileattr' (passing the value // of the variable 'attribute') in the current event // object for all marked files in the current // file manager window fgetfile [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Gets the fully qualified file or directory name at the current line in the current file manager window. returns: a fully qualified file or directory name. fgetopt [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Retrieves the file manager options of the current file manager window. returns: the current file manager option settings see also: fgetsort fgetsort [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Retrieves the sort order of the current file manager window as a one character string (n/s/d/e/o). returns: the current file manager sort order see also: fgetopt, fsort field title x y width initvalue history [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds an edit field window control to the current dialog box. The edit field window becomes the current window. The following parameters may be specified: title - the edit field title or prompt. If the last character of the title is '>', the title will be displayed to the left of the edit field, otherwise the title will be displayed above the edit field. x - the edit field x-position in the dialog box y - the edit field y-position in the dialog box width - the edit field width initvalue - the initial value (if any) to be placed in the edit field history - the history buffer (if any) to be associated with the edit field returns: The edit field window id. see also: button, dialog, groupbox, listbox, whenenter example: dialog "Test Dialog Box" 40 5 // create a dialog box field "Enter string: " 18 2 8 "inital value" // add an edit field control getdialog // display the dialog box file? file path ────────────────────────────────────────────────────────────────────── remarks: Tests for the existence of a file in the specified path. This function is identical to the locatefile function when option 'f' is specified (see 'locatefile'). returns: The fully qualified file if found, otherwise null. see also: directory?, locatefile fileattr? filename attributes=[adhrsv] ────────────────────────────────────────────────────────────────────── remarks: Tests if 'filename' has the specified file attributes. Any combination of the following attributes can be specified: a - archive d - directory h - hidden r - read only s - system v - volume returns: Non-zero if any of the specified attributes are present, otherwise null. see also: getfileattr, setfileattr example: if fileattr? "c:\\file.txt" 'r' then // test for say "Read Only!" // read-only file else // before saving savebuf "c:\\file.txt" end filelist [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a popup menu of buffers which have not been 'hidden'. Selecting a buffer will make it the current buffer and display it in the current edit window. The buffer previously displayed in the edit window will not be destroyed. returns: the bufferid selected, or null if nothing was selected. see also: nextfile, prevfile filepos position opt=[ace] handle ────────────────────────────────────────────────────────────────────── remarks: Changes the current position in the open file specified by 'handle'. If a file handle is not specified, then the file handle returned from the most recent openfile call is assumed. The new position depends on the value of 'position', the current position, and the options specified. One of the following options may be specified: a - the position is an absolute position in the file (1 is the first position) c - the position is an offset from the current position e - the position is an offset from the end of the file. If no options are specified, then 'a' is assumed. returns: The new absolute position in the file (1 is the first position) if successful, otherwise null. see also: closefile, openfile, readfile, writefile fillblock string mark ────────────────────────────────────────────────────────────────────── remarks: Fills a mark with the specified string. If 'string' is not specified, a single blank is assumed. If 'mark' is not specified, the default markid is assumed. returns: TRUE if successful, otherwise null. see also: copystr fillrect length height char col row ────────────────────────────────────────────────────────────────────── remarks: Fills a rectangular area in the current video window with the specified character. 'length' and 'height' specify the dimensions of the rectangular area. 'col' and 'row' specify the upper left corner of the rectangle. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: nothing see also: gotoscreen, hilite, writeline, writestr example: xd = getcoord 'x1' yd = getcoord 'y1' hilite xd yd (getcolor text_color) 1 1 fillrect xd yd ' ' 1 1 // clear the current video window (fill with blanks) find searchstring opt=[abfgilnorswx*[~] mark buffer ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string in a buffer, mark, or line. If 'buffer' is not specified, the current buffer is assumed. Various combinations of the following search options may be specified: a - find all occurrences b - limit the search to the specified mark f - search for closed text folds g - start the search from the beginning or end of the buffer, mark, or line i - ignore case during the search l - limit the search to the current line n - prevent the cursor position from being updated o - search for open text folds r - search in reverse towards the beginning of the buffer, rather than towards the end of the buffer s - skip closed text folds w - search for 'whole words' only x - check for regular expression characters in the search string (see Regexp.dox). * - force the search to begin at the current cursor position instead of the next character position [ - search for the first character also found in the search string. Character ranges can be specified (a-zA-Z, etc.) ~ - search for the first character not found in the search string. Character ranges can be specified (a-zA-Z, etc.) If the string is found, and options 'a' and 'n' are not specified, then the cursor is moved to the beginning of the matched string, otherwise the cursor does not move. returns: If option 'a' is specified, the number of occurrences found is returned, otherwise the length of the matched string is returned. If nothing is found, then null is returned. see also: replace, search example: find "apples" // searches for the string 'apples' (case sensitive) // starting at one char to the right of the cursor // and searching toward the end of the buffer find "apples" "*ir" // searches for 'apples' (case insensitive) starting at // the cursor position and searching toward the // beginning of the buffer find "apples" "bgw" // searches for 'apples' (whole words only), limiting // the search to the current mark and starting from // the beginning of the mark find "{apples}|{oranges}" "agx" // returns the total number of occurrences of the // strings 'apples' and 'oranges' (using regular // expressions) in the current buffer. The cursor is // not moved. find "a-zA-Z" "[gl" // Moves the cursor to the first alphabetic character // in the current line find "^ *$" "agx" // Counts the number of blank lines in the current // buffer using regular expressions findbuf buffername ────────────────────────────────────────────────────────────────────── remarks: Finds the first buffer in the buffer list with the specified buffer name. A buffer name can be associated with a buffer by using the 'setbufname' function. For most ordinary editing buffers, the buffer name is usually a fully qualified file name. returns: The first bufferid with specified name if successful, otherwise null. see also: getcurrbuf, getprevbuf, setbufname example: findbuf "c:\\file.txt" // returns the bufferid of the buffer with the // name c:\file.txt flipcase string ────────────────────────────────────────────────────────────────────── remarks: Toggles the case of each character in the string. returns: the 'flipcased' string. see also: locase, upcase example: flipcase "Oranges" // returns "oRANGES" fmark opt=[amu] [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Marks or unmarks files in the current file manager window. The following options can be specified: a - unmarks all files when specified with option 'u', otherwise all files are marked. m - marks the file or directory at the cursor. If option 'a' is specified, all files are marked. u - unmarks the file or directory at the cursor. If option 'a' is specified, all files and directories are unmarked. If no options are specified, the marked state of the current file or directory is toggled. returns: nothing see also: fbreak, fcommand, fmark? example: fmark // mark the file or directory at the cursor fmark "ma" // mark all files fmark "ua" // unmark all files and directories fmark? [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Tests if any files or directories are marked in the current file manager window. returns: Non-zero if a file or directory is marked, otherwise null. see also: fbreak, fcommand, fmark? fold? opt=[contbsl] row buffer ────────────────────────────────────────────────────────────────────── remarks: This function is a synonym for the 'getfold' function. Calling this function with no arguments is useful for testing whether or not a closed fold exists on the current line in the current buffer. returns: see the 'getfold' function. see also: getfold foldblock opt=[cdkos] mark ────────────────────────────────────────────────────────────────────── remarks: Manipulates folds within a mark. If 'mark' is not specified, the default markid is assumed. The following options may be specified: c - Closes open folds in the mark. If option 's' is also specified, all subfolds are also closed. d - Destroys folds in the mark. The following options may also be specified: s - destroys subfolds c - destroys closed folds o - destroys open folds If option 'd' is specified and options 'o' or 'c' are not specified, then 'dco' is assumed. k - Creates a fold spanning the mark. If option 'o' is also specified, then the fold is created 'open', otherwise the fold is created 'closed'. o - Opens closed folds in the mark. If option 's' is also specified, all subfolds are also opened. If no options are specified, then 'k' is assumed. returns: the number of folds opened, closed, or destroyed. see also: actualrow, apparentrow, closefold, createfold, destroyfold, fold?, getfold, openfold example: foldblock // creates a new closed fold spanning the default mark foldblock 'ds' // destroys all open and closed folds and subfolds // in the default mark foldblock 'o' // opens all top level closed folds in the default mark foldblock 'cs' // closes all open folds and subfolds in the default // mark foldline opt=[u] [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: Folds or unfolds the current line in the current buffer. If option 'u' is specified, the line is unfolded, otherwise the line is folded. returns: nothing see also: actualrow, apparentrow, closefold, createfold, destroyfold, fold?, foldblock, getfold, openfold foldoptions opt=[lr] fillchar window ────────────────────────────────────────────────────────────────────── remarks: Sets options for displaying closed folds. If 'window' is not specified, the current window is assumed. The following options may be specified: l - attempt to display the fold size left-justified at the end of the line. r - attempt to display the fold size right-justified at the right edge of the window If no options are specifed, then the fold size is not displayed. If 'fillchar' character is specified, then fold lines are padded with the specified fill character. returns: nothing see also: getfold forceext filename extension [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Forces a filename to have the specified extension. returns: a filename with the specified extension. see also: defext example: forceext "file" "doc" // returns 'file.doc' forceext "file.txt" "doc" // returns 'file.doc' formatblock leftmarg rightmarg opt=[kjr] mark ────────────────────────────────────────────────────────────────────── remarks: Reformats marked text. If 'mark' is not specified, the default markid is assumed. For column marks, the text is reformatted to fit between the left and right edges of the mark. For all other marks, the text is reformatted to fit between 'leftmarg' and 'rightmarg'. Any combination of the following options may be specified: j - the text is both left and right justified (blanks are inserted to pad text to the right margin) k - attempts to preserve spaces during the reformat r - maintains the indenting relationship between the first and second line of the text returns: TRUE if successful, otherwise null. see also: justblock example: formatblock 5 50 "kr" // reformats the text within a line mark to fit between // columns 5 and 50, preserving spaces and // maintaining the relationship between the first // and second lines in the mark. frame? components window ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified window frame components are present. If 'window' is not specified, the current window is assumed. If no components are specified, all possible components are assumed. See the 'setframe' function for a list of window component options. returns: Non-zero if any of the specified components are present. see also: setframe example: frame? "bn" // returns non-zero if the current window has a // border or a north title bar fsort opt=[ednos] [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Sorts files and directories in the current file manager window. One of the following options can be specified: d - sorts by date and time (descending order) e - sorts by file extension n - sorts by file name o - arrange in the Dos default order s - sorts by file size (descending order) If no options are specified, 'o' is assumed. returns: nothing see also: fgetopt, fgetsort, pickfile example: fsort 'n' // sort by file name fsort 's' // sort by size (descending) fstatus [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Updates the status line of the current file manager window. returns: nothing function? function object ────────────────────────────────────────────────────────────────────── remarks: Tests for the existence of a public function defined by 'function' in the object defined by 'object'. If 'object' is not specified, then the current object is assumed. The inheritance hierarchy of the specified object may also be searched for the function. returns: Non-zero if the function exists, otherwise null. see also: destroyvar, lookup, set, variable? example: function? "function?" // returns non-zero function? "markword" "edit" // tests if the 'markword' function is accessible // from within the object 'edit' fup [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Reloads the current file manager window with the parent directory of the currently displayed directory. returns: TRUE if successful, otherwise null. see also: open, reopen fupdate file fmgroptions [Lib][fmgr] ────────────────────────────────────────────────────────────────────── remarks: Updates the current file manager window without reloading the directory (as the reopen command does). If file manager options are not specified, the file manager options associated with the current window are used. If 'file' is specified, the current line is replaced with the specified file. If no file is specified, then the entire file manager window is updated. returns: nothing see also: fgetopt, reopen getattr x y ────────────────────────────────────────────────────────────────────── remarks: Gets the color at the specified x,y position in the current video output window. If x or y are not specified, the current video cursor position is assumed. returns: the color at x,y see also: fillrect, getstr, getx, gety, gotoxy, gotoscreen, hilite, writeline, writestr getbinarylen buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the binary line length that was used to load a binary buffer. If 'buffer' is null or not specified, then the current buffer is assumed. This function can also be used to test if a buffer is a binary buffer. returns: The line length associated with a binary buffer. If the buffer is not binary, then zero is returned. see also: createbbuf, insertbuf, loadbuf getbookbuf bookmark ────────────────────────────────────────────────────────────────────── remarks: Retrieves the buffer associated with a bookmark. If 'bookmark' is not specified, the current 'bookmark' in the current buffer is assumed. returns: The bufferid associated with the bookmark if successful, otherwise null. see also: getcurrbook getbootpath ────────────────────────────────────────────────────────────────────── remarks: Retrieves the editor 'boot' path. The boot path is the location of the editor .Exe file currently executing. returns: The boot path. see also: bootpath, setbootpath getborder opt=[xyt] window ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about a window border. If 'window' is not specified, the current window is assumed. One of the following options can be specified: x - returns the width of the left and right borders y - returns the width of the top and bottom borders t - returns the border type, See the 'setborder' function for a description of border types. returns: Information based on the options specified. see also: setborder getbotwin ────────────────────────────────────────────────────────────────────── remarks: Gets the bottommost window on the screen. returns: the windowid of the bottommost window on the screen see also: getcurrwin getbufname buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the descriptive name associated with a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. A buffer name can be associated with a buffer by using the 'setbufname' function. For most ordinary editing buffers, the buffer name is usually a fully qualified file name. returns: The descriptive name associated with a buffer. see also: findbuf, setbufname getbuftabs buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the tab width used for displaying real tabs. If 'buffer' is not specified, the current buffer is assumed. returns: the tab width see also: setbuftabs getchar col row buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the character at the specified column and row in the buffer 'buffer'. If 'buffer' is null or not specified, then the current buffer is assumed. If 'col' and 'row' are not specified, then the character at the cursor is retrieved. If the column is beyond the end of a line, null is returned. returns: A one-character string if successful, otherwise null. see also: getrealtext, gettext example: getchar // returns the character at the cursor in the // current buffer getchar 3 5 // returns the character at column 3, line 5 in the // current buffer getchar 1 1 "abc" // returns the first character in the buffer "abc" getchild window opt=[bt] ────────────────────────────────────────────────────────────────────── remarks: Gets a child window for a window. If 'window' is not specified, the current window is assumed. The following options may be specified: b - returns the bottommost child window t - returns the topmost child window returns: the windowid of the topmost or bottommost child window if successful, otherwise null. see also: getparent, setnextwin, setparent, setprevwin getcol buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the column position of the cursor. If 'buffer is null or not specified, the current buffer is assumed. returns: The current cursor column position. see also: getrow getcolor component window ────────────────────────────────────────────────────────────────────── remarks: Gets the color of a window component. If 'window' is not specified, the current window is assumed. See the 'setcolor' function for 'component' values. returns: the color of the specified window component. see also: setcolor example: getcolor 5 // returns the text color of the current window getcolor 6 // returns the mark color of the current window getcoord opt=[ltrb1xyd] window ────────────────────────────────────────────────────────────────────── remarks: Retrieves the coordinates and dimensions of a window. If 'window' is not specified, the current window is assumed. The following options may be specified: l - returns the virtual left edge of the window t - returns the virtual top edge of the window r - returns the virtual right edge of the window b - returns the virtual bottom edge of the window x - returns the window width (the width of the client area if option '1' is specified) y - returns the window height (the height of the client area if option '1' is specified) d - clip the height, width, or coordinate with the visible portion of the display. 0 - returns a main window coordinate 1 - returns a client window coordinate. If not specified, main window coordinates are assumed. returns: Information based on the options specified. see also: movewindow, sizewindow example: getcoord "l" // return the virtual coordinate of the left edge of // the current window getcoord "1xd" // returns the visible width of the current window // client area on the screen getcurrbook buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current bookmark for the specified buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current bookmarkid for a buffer. see also: currbook getcurrbuf ────────────────────────────────────────────────────────────────────── remarks: Gets the current buffer at the top of the buffer list. returns: The current bufferid if successful, otherwise null. see also: findbuf, getprevbuf, gotobuf getcurrcurs buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current cursorid for the specified buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current cursorid for a buffer. see also: currcursor, destroycursor, setcursor getcurrfile ────────────────────────────────────────────────────────────────────── remarks: Gets the name of the macro language file being currently compiled or executed. returns: If called from within the constant or #exec statements, the name of the file being currently compiled is returned, otherwise the name of the file being currently executed is returned. see also: constant, #exec, geterror getcurrmark buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current markid for the specified buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current markid for a buffer. see also: currmark getcurrobj ────────────────────────────────────────────────────────────────────── remarks: Gets the current (executing) object where this function is called. returns: The current object. see also: object getcurrpath drive ────────────────────────────────────────────────────────────────────── remarks: Retrieves the current path for the specified disk drive. If 'drive' is not specified, the current drive is assumed. If a drive is specified, it must be specified with a colon: 'C:', 'D:', etc. returns: The current fully qualified path for the specified drive. see also: currpath getcurrwin opt=[c] ────────────────────────────────────────────────────────────────────── remarks: Gets the current (topmost) window on the screen. If no options are specified, the topmost non-child window is returned. If option 'c' is specified, the topmost window is returned, whether or not the window is a child window. returns: the current windowid see also: getbotwin, gotowindow getcursbuf cursor ────────────────────────────────────────────────────────────────────── remarks: Retrieves the buffer associated with a cursor. If 'cursor' is not specified, the current 'cursor' in the current buffer is assumed. returns: The bufferid associated with the cursor if successful, otherwise null. see also: getcurrbook getcurswin cursor ────────────────────────────────────────────────────────────────────── remarks: Retrieves the windowid (if any) associated with a cursor. If 'cursor' is not specified, the current 'cursor' in the current buffer is assumed. returns: The windowid associated with a cursor if successful, otherwise null. see also: getwincurs getdate format ────────────────────────────────────────────────────────────────────── remarks: Gets the current date in the specified format. If 'format' is not specified, the format previously passed to the 'international' function is assumed. See the 'international' function for a list of valid date formats. returns: The current date. see also: getfileinfo, getrawtime, gettime, international getdialog ref1 ref2 ... [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the current dialog box as a modal dialog box (existing windows on the screen cannot be placed on top of a modal dialog box). This function does not return until the dialog box has been closed. The current dialog box control values are returned in the variables (ref1, ref2, etc.) passed by reference to this function. The order of the return values is the same order in which the dialog box controls were defined. The following values are returned for each control: button - null field - the contents of the edit field group - the checked items in the group box, in 'initvalue' format (see the 'groupbox' function) listbox - the line at the cursor within the list box returns: The title of the button pressed to close the window. If <enter> is pressed then 'Ok' is returned. If <esc> is pressed, then null is returned. If the 'close' function is called from within a dialog box event-handling function (defined with 'whenenter' or 'whenselect'), then the first argument passed to 'close' is returned. Dialog box control values are also returned in variables passed by reference to this function. see also: dialog, showdialog, whenenter, whenselect example: dialog "Test Dialog Box" 40 17 field "Enter string1: " 18 2 8 field "Enter string2: " 18 4 8 variable field1 variable field2 // display the dialog box, and get return values if (getdialog ref field1 ref field2) == 'Ok' then : end getdisk opt=[cfmnv] drive ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about the specified disk drive. If a drive is not specified, the current drive is assumed. The following options can be specified: c - returns the total drive capacity f - returns the free space on the drive m - returns a string composed of all available disk drive letters. If option 'n' is also specified, each drive letter is followed by '2' if a network drive or '1' if not a network drive v - returns the volume name for the drive returns: Information based on the specified options. see also: getcurrpath example: getdisk 'f' // returns the free space on the current drive getdisk 'v' "c:" // returns the volume name for drive C getenv variable ────────────────────────────────────────────────────────────────────── remarks: Gets the value of the specified environment variable. 'variable' must be in upper case. returns: The value of an environment variable if successful, otherwise null. see also: getos example: getenv "PATH" // returns the Dos 'PATH' string geterror opt=[cfkls] ────────────────────────────────────────────────────────────────────── remarks: Retrieves error information after compiling macro source code with the 'compilemacro' or 'eval' functions, or executing macros with the 'runmacro' and 'loadobject' functions. One of the following options can be specified: c - error code (zero if successful) f - source filename where the error occurred k - column in the source file where the error occurred l - line in the source file where the error occurred s - an error information string. The string contents depend on the error code (see the 'compilemacro' and 'seterror' functions for additional information). If no options are specified, 'c' is assumed. returns: Information based on the options specified. see also: compilemacro, eval, runmacro, seterror geteventcode eventname ────────────────────────────────────────────────────────────────────── remarks: Gets the event code for the specified event name. returns: an event code see also: geteventname example: say "The keycode for <ctrl b> is: " + (geteventcode "<ctrl b>") geteventcount ────────────────────────────────────────────────────────────────────── remarks: Gets the number of real physical events (keyboard and mouse) which have occurred in the current editing session. returns: The number of real events. see also: event?, keyhit?, shiftkey? geteventobj ────────────────────────────────────────────────────────────────────── remarks: Gets the current event object. The current event object is the object where events are dispatched by the editor. returns: The current event objectid. see also: seteventobj getexe ────────────────────────────────────────────────────────────────────── remarks: Gets the name of the currently executing editor .Exe file, without the path or file extension. returns: The editor .Exe name. see also: getversion getos getfileinfo filename opt=[adtrs] ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about the specified file or directory. Any one of the following options may be specified: a - return the file attributes as a 4-character string d - return the file date in international format t - return the file time in international format r - return the file date and time in raw format s - return the file size in bytes If option 'r' is specified, the raw time will contain '0' for the day-of-the-week and hundredths of a second (see 'getrawtime'). returns: Information based on the options specified see also: getdate, getrawtime, gettime getfold opt=[contbsl] row buffer ────────────────────────────────────────────────────────────────────── remarks: Returns information about a fold at the specified row in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. The following options may be specified: l - Returns the line number of the top or bottom row in an open fold. The following options may also be specified: t - returns the top line number b - returns the bottom line number If options 't' and 'b' are not specified, then 't' is assumed. n - Returns the total number of folds in the buffer ('row' is ignored). The following options may be specified: c - returns the total number of closed folds o - returns the total number of open folds If options 'c' and 'o' are not specified, then 'co' (both open and closed folds) is assumed. s - returns the number of lines in the closed fold at the specified row. If none of the above options are specified, then the following options may be used to test whether or not the current line is on a fold boundary: c - returns true if the specified row is on the top or bottom line of a closed fold. o - returns true if the specified row is on the top or bottom line of an open fold. t - returns true if the specified row is on the top line of a fold. b - returns true if the specified row is on the bottom line of a fold. If no options are specified, then 'ct' is assumed. returns: Information based on the options specified. see also: actualrow, apparentrow, closefold, createfold, destroyfold, fold?, foldblock, foldoptions, openfold example: getfold // returns true if a closed fold exists at the cursor // in the current buffer getfold 'ot' // returns true if the cursor is on the top line of // an open fold getfold 'ns' // returns the total number of closed folds in the // current buffer getfold 's' // returns the number of lines in the closed fold at // the cursor in the current buffer gethistname [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Gets the history bufferid for the current prompt. This function is only for use within prompts. returns: the history bufferid for the current prompt. see also: addhistory, askhistory, gethiststr, pophistory gethiststr historybuffer [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Gets the most recently used (or added) string for the specified history buffer. returns: the most recently used history string. see also: addhistory, askhistory, pophistory example: addhistory "_find" "apples" say (gethiststr "_find") // displays 'apples' getkey opt=[ds] ────────────────────────────────────────────────────────────────────── remarks: Waits for a key to be entered, bypassing the editor event queue. The display is updated if needed. The following options may be specified: d - disable updating of the display s - include scancodes for non-function (typeable) keys returns: A keycode for the key pressed. see also: geteventcode, geteventname example: say "you pressed keycode: " + getkey geteventname eventcode ────────────────────────────────────────────────────────────────────── remarks: Gets the event name for the specified event code. returns: an event name see also: geteventcode example: say "You pressed the key: " + (geteventname (getkey)) getlinebeg row buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the column of the first non-blank, non-tab character in a line. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: The column of the first non-blank, non-tab character, otherwise null. see also: getlinelen, getlinesize example: getlinebeg // returns the first non-blank column of the current // line in the current buffer getlinelen 1 // returns the first non-blank column of the first // line in the current buffer getlinebeg 5 "abc" // returns the first non-blank column of line 5 in // buffer "abc" getlinelen row buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the length of a line. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. returns: For non-binary buffers, the position of the last non-blank, non-tab character in the line is returned. For binary buffers, the position of the last character in the line is returned. see also: getbinarylen, getlinebeg, getlinesize example: getlinelen // returns the length of the line at the cursor in // the current buffer getlinelen 1 // returns the length of the first line in the // current buffer getlinelen 5 "abc" // returns the length of line 5 in the buffer "abc" getlines buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the total number of lines in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. A buffer will always have at least one line. returns: The number of lines in a buffer. getlinesize row buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the length of a line. This function is nearly identical to the getlinelen function, except that the returned line length includes trailing blanks and tabs. returns: the actual line length see also: getlinebeg, getlinelen getloadinfo opt=[dfst] ────────────────────────────────────────────────────────────────────── remarks: Obtains information about the file or directory which was loaded by the most recent 'loadbuf' or 'insertbuf' function call. One of the following options can be specified: d - return the number of subdirectories for a directory load f - return the number of files for a directory load s - return total size of all files for a directory load t - return the load type: 0 for files, 1 for directories returns: Information based on the options specified. see also: insertbuf, loadbuf getmarkbot mark ────────────────────────────────────────────────────────────────────── remarks: Gets the bottommost line of a mark. If 'mark' is not specified, the default markid is assumed. returns: The bottommost line of the mark if successful, otherwise null. see also: getmarkleft, getmarkright, getmarktop getmarkbuf mark ────────────────────────────────────────────────────────────────────── remarks: Retrieves the buffer associated with a mark. If 'mark' is not specified, the default markid is assumed. returns: The bufferid of the buffer associated with the mark if successful, otherwise null. see also: getcurrmark getmarkcols mark ────────────────────────────────────────────────────────────────────── remarks: Gets the width of a mark. For line marks, 16001 is returned. For column, character, and stream marks, the end column minus the start column plus 1 is returned. If 'mark' is not specified, the default markid is assumed. returns: The mark width if successful, otherwise null. see also: getmarkrows getmarkleft mark ────────────────────────────────────────────────────────────────────── remarks: Gets the leftmost column of a mark. For line marks, zero is returned. For character and stream marks, the starting column of the mark is returned. If 'mark' is not specified, the default markid is assumed. returns: The leftmost column of the mark if successful, otherwise null. see also: getmarkbot, getmarkright, getmarktop getmarkright mark ────────────────────────────────────────────────────────────────────── remarks: Gets the rightmost column of a mark. For line marks, 16001 is returned. For character and stream marks, the ending column of the mark is returned. If 'mark' is not specified, the default markid is assumed. returns: The rightmost column of the mark if successful, otherwise null. see also: getmarkbot, getmarkleft, getmarktop getmarkrows mark ────────────────────────────────────────────────────────────────────── remarks: Gets the mark height (the number of lines spanned by the mark). If 'mark' is not specified, the default markid is assumed. returns: The mark height if successful, otherwise null. see also: getmarkcols getmarktop mark ────────────────────────────────────────────────────────────────────── remarks: Gets the topmost line of a mark. If 'mark' is not specified, the default markid is assumed. returns: The topmost line of the mark if successful, otherwise null. see also: getmarkbot, getmarkleft, getmarkright getmarktype mark ────────────────────────────────────────────────────────────────────── remarks: Gets the mark type (column, line, character, or stream). If 'mark' is not specified, the default markid is assumed. returns: A one-byte string indicating the mark type: l - line mark k - column mark c - character mark s - stream mark see also: markchar, markcolumn, markline, markstream getmarkuse ────────────────────────────────────────────────────────────────────── remarks: Gets the default markid. returns: the default markid. see also: usemark getmenu opt=[hwnxym] row menubuffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about a menu buffer created with the 'menu' keyword. 'menubuffer' specifies the name of the menu. If 'menubuffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. One of the following options can be specified. h - return the menu highlight column for the row m - return TRUE if the buffer is a menu buffer n - return the menu item description text w - return the menu width y - return the cursor row at last menu exit x - return the menu item compiled macro code (if any) returns: Information based on the options specified. see also: menu getmenubar opt=[cfnosw] menubar[1-4] item window ────────────────────────────────────────────────────────────────────── remarks: Retrieves information about a menu bar. If 'window' is not specified, the current window is assumed. 'menubar' specifies one of the 4 possible menu bars for a window. If 'menubar' is not specified, 1 is assumed (the primary menu bar). 'item' is an integer specifying the relative position of a menu bar item from the beginning of the menu bar. If 'item' is not specified, the current highlighted menu bar item is assumed. The following options may be specified: c - returns the highlighted character for a menu bar item f - returns the menu bar item function string n - returns the total number of menu bar items o - returns the offset (in columns) of the menu bar item description text from the beginning of the menu bar s - returns the menu bar item description text w - returns the menu bar width (for west menus only) If no options are specified, the current highlighted menu bar item is returned. returns: Information based on the options specified see also: hilitebar, menubar example: getmenubar // returns the currently highlighted item on the // primary menu bar (tests if an item is highlighted) getmenubar 'n' 2 // returns the total number of menu bar items for // menu bar 2 getmenubar 's' '' 3 // returns the description for the third menu bar item // on the primary menu bar getmousex opt=[e] ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual X coordinate of the mouse pointer. If option 'e' is specified, the X coordinate where the last mouse event occurred is returned. returns: the mouse virtual X coordinate see also: getmousex, mousepos getmousey opt=[e] ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual Y coordinate of the mouse pointer. If option 'e' is specified, the Y coordinate where the last mouse event occurred is returned. returns: the mouse virtual Y coordinate see also: getmousey, mousepos getnextwin window opt=[z] ────────────────────────────────────────────────────────────────────── remarks: Gets the window after 'window' the window list. If 'window' is not specified, the current window is assumed. If option 'z' is specified, any window may be returned, otherwise only a window at the same child-level as 'window' is returned. returns: the windowid of the next window if successful, otherwise null. see also: getchild, getprevwin getos opt=[vml] ────────────────────────────────────────────────────────────────────── remarks: Gets information about the operating system. One of the following options may be specified: v - return the major Dos version number m - return the minor Dos version number l - return TRUE if long filenames are supported If no options are specified, the operation system name 'Dos' is returned. returns: The operating system name or version. see also: getversion getpalette position ────────────────────────────────────────────────────────────────────── remarks: Retrieves a color attribute from a 100-byte user-defined palette area defined with the 'setpalette' function. If no position is specified, the entire palette area is returned. The editor library code (Lib.x) expects color attributes to be in the positions defined in Color.aml. returns: a numeric color attribute, or the 100-byte palette. see also: Color.aml, setpalatte getparent window ────────────────────────────────────────────────────────────────────── remarks: Gets the parent window of a window. If 'window' is not specified, the current window is assumed. returns: the windowid of the parent window if successful, otherwise null. see also: getchild, setparent getprevbook bookmark ────────────────────────────────────────────────────────────────────── remarks: Gets the bookmark preceding 'bookmark' in the bookmark list for the current buffer. If 'bookmark' is not specified, the current bookmark in the current buffer is assumed. returns: The bookmarkid of the previous bookmark if successful, otherwise null. see also: currbook getprevbuf buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the buffer before 'buffer' in the buffer list. If 'buffer' is null or not specified, then the current buffer is assumed. returns: The previous bufferid, or null if no previous buffer exists. see also: findbuf, getcurrbuf example: buffer = getcurrbuf // cycles through existing while buffer do // buffers buffer = getprevbuf buffer end getprevcurs cursor ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor before 'cursor' in the cursor list for the current buffer. If 'cursor' is not specified, the current cursor in the current buffer is assumed. returns: The cursorid of the previous cursor if successful, otherwise null. see also: currcursor getprevmark mark ────────────────────────────────────────────────────────────────────── remarks: Gets the mark preceding 'mark' in the mark list for the current buffer. If 'mark' is not specified, the default markid is assumed. returns: The markid of the previous mark if successful, otherwise null. see also: currmark getprevwin window opt=[z] ────────────────────────────────────────────────────────────────────── remarks: Gets the window before 'window' the window list. If 'window' is not specified, the current window is assumed. If option 'z' is specified, any window may be returned, otherwise only a window at the same child-level as 'window' is returned. returns: the windowid of the previous window if successful, otherwise null. see also: getchild, getnextwin getrawtime ────────────────────────────────────────────────────────────────────── remarks: Gets the current date and time in a 17 character string. The format of the string is as follows: format: YYYYMMDDWhhmmssuu where: YYYY = year MM = month [1-12] DD = day [1-31] W = day of the week [0-6, 0=sunday] hh = hour [0-23] mm = minutes [0-59] ss = seconds [0-59] uu = hundredths of a second [0-99] returns: The current date and time in raw format. see also: getdate, getfileinfo, gettime getrealtext col length row buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves text within a line. This function is nearly identical to the gettext function, except that it returns the text at the original physical memory location in the buffer (unlike the gettext function, which returns a copy). The text returned from this function must be used immediately, since the editor automatically changes memory contents as needed. This function is useful when the actual physical address of buffer text is needed for machine language functions, or for optimizing macros where the text will be used immediately. returns: a line or a portion of a line see also: getchar, gettext getregion virtualX virtualY window ────────────────────────────────────────────────────────────────────── remarks: Returns an integer code identifying the region of a window containing the virtual screen coordinate 'virtualX', 'virtualY'. If 'window' is not specified, the current window is assumed. If 'virtualX' and 'virtualY' are not specified, the current mouse position is assumed. This function is useful for determining where a mouse click occurred. The following table shows the integer codes and the corresponding window regions: code region ──── ────── 0 'virtualX', 'virtualY' is not in the window 1 client area 2 north border 3 east border 4 south border 5 west border 6 northwest border corner 7 northeast border corner 8 southeast border corner 9 southwest border corner 11 north title bar 12 south title bar 13 west title 14 east title 19 vertical & horizontal scroll bar intersection 21 vertical scroll bar up arrow 22 vertical scroll bar down arrow 23 vertical scroll bar page-up bar 24 vertical scroll bar page-down bar 25 vertical scroll bar thumb 31 horizontal scroll bar left arrow 32 horizontal scroll bar right arrow 33 horizontal scroll bar page-left bar 34 horizontal scroll bar page-right bar 35 horizontal scroll bar thumb 51 - 100 window title bar controls from left to right 101 - 200 primary menu bar items from left to right 201 - 300 menu bar 2 items from left to right 301 - 400 menu bar 3 items from left to right 401 - 500 menu bar 4 items from left to right returns: a window region code. example: function <lbutton> // determine where a left mouse case getregion // button click occurred when 1 ... // client area? when 11 ... // north title bar? : end end getrow buffer ────────────────────────────────────────────────────────────────────── remarks: Gets the current line number of the cursor. If 'buffer' is null or not specified, the current buffer is assumed. returns: The current line number of the cursor. see also: getcol, getlines getsettings [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Gets the current window settings as they appear on the edit window title bar. See the 'setting' command for a description of window settings. returns: a string containing the current window settings. see also: setting, setting? getstr length x y ────────────────────────────────────────────────────────────────────── remarks: Gets a string of the specified length at the specified x,y position in the current video output window. If x or y are not specified, the current video cursor position is assumed. returns: the string at x,y see also: fillrect, getattr, getx, gety, gotoxy, gotoscreen, hilite, writeline, writestr getsyntax window ────────────────────────────────────────────────────────────────────── remarks: Retrieves the syntax highlighting object associated with a window. If 'window' is not specified, the current window is assumed. returns: a syntax highlighting object see also: setsyntax gettext col length row buffer ────────────────────────────────────────────────────────────────────── remarks: Retrieves text within a line in the specified buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If 'col' is not specified, then column one is assumed. If 'length' is not specified, then the length from the specified column to the end of the line is assumed. If 'col' is beyond the end of the line, then null is returned. returns: A copy of a line (or portion of the line) if successful, otherwise null. see also: getchar, getrealtext example: gettext // returns the line at the cursor in the current buffer gettext 3 // returns the portion of the current line from // column 3 to the end of the line gettext 3 5 // returns 5 characters at column 3, on the current line // in the current buffer gettext 3 5 20 "abc" // returns 5 characters at column 3, line 20 in the // buffer "abc" gettitle titleid[1-5] window opt=[h] ────────────────────────────────────────────────────────────────────── remarks: Gets a window title string for a window. If 'window' is not specified, the current window is assumed. 'titleid' specifies which window title to retrieve. If 'titleid' is zero, then one is assumed (the primary title). If option 'h' is specified, then this function returns the highlighted position within the title string. returns: a window title string. see also: settitle example: gettitle // returns title 1 for the current window gettitle 3 "abc" // returns title 3 for window "abc" gettime format ────────────────────────────────────────────────────────────────────── remarks: Gets the current time in the specified format. If 'format' is not specified, the format previously passed to the 'international' function is assumed. If the format is -1, the international format is assumed, but with seconds added (if not already present). See the 'international' function for a list of valid time formats. returns: The current time. see also: getdate, getfileinfo, getrawtime, international getversion ────────────────────────────────────────────────────────────────────── remarks: Gets the current version of the editor. returns: The current version (major and minor) of the editor as a string. see also: getexe, getos getvidbot ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the bottommost row of the physical screen. returns: the bottom edge of the physical screen. see also: getvidleft, getvidright, getvidrows, getvidtop getvidcols ────────────────────────────────────────────────────────────────────── remarks: Gets the number of columns on the screen. returns: the number of columns on the screen. see also: getvidleft, getvidright, getvidrows getvidleft ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the leftmost column of the physical screen. returns: the left edge of the physical screen. see also: getvidbot, getvidcols, getvidright, getvidtop getvidright ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the rightmost column of the physical screen. returns: the right edge of the physical screen. see also: getvidbot, getvidcols, getvidleft, getvidtop getvidrows ────────────────────────────────────────────────────────────────────── remarks: Gets the number of rows on the screen. returns: the number of rows on the screen. see also: getvidbot, getvidcols, getvidtop getvidtop ────────────────────────────────────────────────────────────────────── remarks: Gets the virtual coordinate of the topmost row of the physical screen. returns: the top edge of the physical screen. see also: getvidbot, getvidleft, getvidright, getvidrows getviewbot window ────────────────────────────────────────────────────────────────────── remarks: Gets the line number of the bottommost visible row in a window. If 'window' is not specified, the current window is assumed. returns: the bottommost visible row in a window. see also: getviewleft, getviewright, getviewtop getviewcols window ────────────────────────────────────────────────────────────────────── remarks: Gets the number of visible columns in a window. If 'window' is not specified, the current window is assumed. returns: the number of visible columns. see also: getviewleft, getviewright, getviewrows getviewleft window ────────────────────────────────────────────────────────────────────── remarks: Gets the leftmost column in a window. If 'window' is not specified, the current window is assumed. returns: the leftmost column in a window. see also: getviewbot, getviewright, getviewtop getviewright window ────────────────────────────────────────────────────────────────────── remarks: Gets the rightmost visible column in a window. If 'window' is not specified, the current window is assumed. returns: the rightmost visible column in a window. see also: getviewbot, getviewleft, getviewtop getviewrows window ────────────────────────────────────────────────────────────────────── remarks: Gets the number of visible rows in a window. If 'window' is not specified, the current window is assumed. returns: the number of visible rows. see also: getviewbot, getviewcols, getviewtop getviewtop window ────────────────────────────────────────────────────────────────────── remarks: Gets the line number of the topmost row in a window. If 'window' is not specified, the current window is assumed. returns: the topmost row in a window. see also: getviewbot, getviewleft, getviewright getwinbuf window ────────────────────────────────────────────────────────────────────── remarks: Gets the buffer associated with a window. If 'window' is not specified, the current window is assumed. returns: the bufferid associated with the window is successful, otherwise null. see also: getwincurs, setwincurs getwincount window ────────────────────────────────────────────────────────────────────── remarks: Gets the number of windows on the screen. If 'window' is specified, this function returns the number of child windows attached to 'window'. returns: the number of windows on the screen, or the number of child windows attached to a window. see also: getchild, setparent getwinctrl window ────────────────────────────────────────────────────────────────────── remarks: Gets the title bar controls for a window. If 'window' is not specified, the current window is assumed. returns: a string containing all the title bar controls see also: setwinctrl getwincurs window ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor associated with a window. If 'window' is not specified, the current window is assumed. Only cursors associated with a buffer are returned. returns: the cursorid of the window cursor if successful, otherwise null. see also: getwinbuf, setwincurs getwinobj window ────────────────────────────────────────────────────────────────────── remarks: Gets the event object associated with a window. If 'window' is not specified, the current window is assumed. returns: the window event object. see also: setwinobj getwinscr virtualX virtualY window ────────────────────────────────────────────────────────────────────── remarks: Translates a virtual x,y coordinate in a scroll bar to a column or row in a window. If 'window' is not specified, the current window is assumed. This function can be used to translate a mouse pointer position in a scroll bar to a position in a window. returns: A window column if virtualX, virtualY lies within a horizontal scroll bar, or a window row if virtualX, virtualY lies within a vertical scroll bar, otherwise null. see also: getviewbot, getviewleft, getviewright, getviewtop getx ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor column in the current video window. This function is ignored for windows which contain a buffer. returns: the cursor column in the current video window see also: fillrect, getattr, getstr, gety, gotoxy, gotoscreen, hilite, writeline, writestr gety ────────────────────────────────────────────────────────────────────── remarks: Gets the cursor row in the current video window. This function is ignored for windows which contain a buffer. returns: the cursor row in the current video window see also: fillrect, getattr, getstr, getx, gotoxy, gotoscreen, hilite, writeline, writestr gotobar item [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Activates the specified menu bar item from the primary menu bar. 'item' specifies the menu bar item or the menu bar description text. returns: nothing see also: getmenubar, gotobar2, menubar example: gotobar 1 // highlights the 'File' menu bar item gotobar "File" // highlights the 'File' menu bar item gotobar2 item [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Activates the specified menu bar item on the toolbar of an edit window, or the drive bar of a file manager window. 'item' specifies the menu bar item or the menu bar description text. returns: nothing see also: getmenubar, gotobar, menubar gotobook bookmark ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to a bookmark. Only the current cursor in the buffer associated with the bookmark is moved. If 'bookmark' is not specified, the current 'bookmark' in the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: getcurrbook, setbook gotobuf buffer ────────────────────────────────────────────────────────────────────── remarks: Makes the specified buffer the current buffer. If 'buffer' is not specified, the buffer at the top of the buffer list becomes the current buffer. Unlike the 'currbuf' function, the position of the buffer in the buffer list is not changed. returns: The previous current buffer if successful, otherwise null. see also: currbuf, findbuf, getcurrbuf example: oldbuffer = gotobuf 'abc' // switch to buffer 'abc' : gotobuf oldbuffer // switch back to the old buffer gotomatch char-pairs [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Finds the matching character for a character specified in 'char-pairs'. returns: Non-zero if found, otherwise null. example: gotomatch "(){}[]<>" gotomenu pulldown [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified pulldown menu from the primary menu bar. 'pulldown' specifies the menu bar item or menu bar item description for the pulldown menu. returns: nothing see also: getmenu, menu, submenu example: gotomenu 1 // displays the 'File' pulldown menu gotomenu "File" gotopos col row buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified column and row. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor line number if successful, otherwise null. see also: col, row, movepos example: gotopos 1 1 // moves the cursor to column one of the first line gotoscreen ────────────────────────────────────────────────────────────────────── remarks: Changes all video functions to operate immediately on the actual physical screen. The physical screen becomes the current window for all builtin video functions. Column one and row one are located at the upper left corner of the screen. This function can be used to perform custom drawing of the display. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotowindow, gotoxy, hilite, writeline, writestr gotowindow window ────────────────────────────────────────────────────────────────────── remarks: Makes the specified window the current window. If 'window' is not specified, the topmost window on the screen becomes the current window. Note that this function does not change the ordering of windows on the screen. It changes the 'current' or default window referenced in builtin window functions. returns: The previous current window if successful, otherwise null. see also: getcurrwin, gotoscreen gotoxy col row ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified column and row in the current video window. This function is ignored for windows which contain a buffer. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, hilite, writeline, writestr groupbox title x y buffer width initvalue valuemap [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds a group box window control to the current dialog box. The group box window becomes the current window. The group box may contain check boxes or radio buttons. The following parameters may be specified: title - the group box title x - the group box x-position in the dialog box y - the group box y-position in the dialog box buffer - the menu buffer to display in the group box width - the group box width (if not specified, the title width or widest menu item width is used, whichever is widest) initvalue - the values (if any) used to intialize the group box. Initial values are entered as a string of one-character codes, with each character representing a checked menu item from a string of possible choices specified by the 'valuemap' argument. If 'initvalue' is not specified, the first menu item is checked. valuemap - a string of possible choices of one-character codes for 'initvalue', which each character representing a menu item. The first character in the string represents the first menu item, the second character represents the second menu item, and so on. A group box menu item is a check box if the characters '[ ]' are the the first 4 characters in the menu item. The menu item is a radio button if the characters ' ( )' are the the first 4 characters in the menu item. returns: The group box window id. see also: button, dialog, field, listbox, setgroupbox, whenenter, whenselect example: dialog "Test Dialog Box" 40 8 // create a dialog box groupbox 'Group Box:' 22 2 ( menu '' item " [ ] &Apples" item " [ ] &Oranges" item " [ ] &Melons" item " [ ] &Bananas" end ) 15 'am' 'aomb' // add a group box containing check boxes, initially // checking the first and third menu items getdialog // display the dialog box halt ────────────────────────────────────────────────────────────────────── remarks: Terminates the execution of the editor immediately and unconditionally. returns: nothing see also: delay, machine, system hex2bin hexstring ────────────────────────────────────────────────────────────────────── remarks: Converts a hexadecimal string, composed of only the characters 0-9 and A-F or a-f, to a binary string. returns: a binary string. see also: bin2hex example: hex2bin "61" // returns 'a' hex2bin "616263" // returns 'abc' hidecursor ────────────────────────────────────────────────────────────────────── remarks: Hides the physical cursor in the current window. If the current window contains a buffer, the effects of this function are temporary and will disappear the next time the display is updated. returns: nothing see also: showcursor hidemouse ────────────────────────────────────────────────────────────────────── remarks: Hides the mouse pointer. returns: nothing see also: showmouse hidewindow window ────────────────────────────────────────────────────────────────────── remarks: Hides a window temporarily. If 'window' is null or not specified, then the current window is assumed. The window will be shown again the next time the display is updated. returns: nothing see also: showwindow hilite length height color col row ────────────────────────────────────────────────────────────────────── remarks: Highlights a rectangular area in the current window with the specified color attribute. 'length' and 'height' specify the dimensions of the highlighted rectangle. 'col' and 'row' specify the upper left corner of the rectangle. If 'col' and 'row' are not specified, the current cursor position is assumed. If the current window displays a buffer, the effects of this function are temporary and will disappear the next time the display is updated. If the current window does not display a buffer and 'height' is one, the current cursor position is moved to the right of the highlighted area. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, gotoxy, writeline, writestr example: hilite 6 1 95 // highlights a word at the cursor of length 6 // with the color 'white on magenta' hilitebar menubar[1-4] item window ────────────────────────────────────────────────────────────────────── remarks: Highlights or un-highlights a menu bar item in a window. There can only be one highlighted item per menu bar. If 'window' is not specified, the current window is assumed. 'menubar' specifies one of the 4 available menu bars in the window. If 'menubar' is not specified, 1 is assumed (the primary menu bar). 'item' indicates the relative position of the menu bar item from the beginning of the menu bar (1 for the first item, 2 for the second item, and so on). If 'item' is null or zero, then the highlight is removed from any currently highlighted item in the menu bar. returns: If successful, the offset (in character positions) of the specified menu bar item from the beginning of the menu bar, otherwise null. see also: getmenubar, menubar example: hilitebar // removes the highlight from the primary menu bar hilitebar 2 5 // highlights item 5 on menu bar 2 icompare string1 string2 ... ────────────────────────────────────────────────────────────────────── remarks: Tests if 'string1' is equal to any of the following arguments, ignoring case. returns: TRUE if the comparison succeeds, otherwise null. see also: flipcase, locase, upcase example: icompare "apples" "Apples" // returns TRUE icompare "apples" "oranges" // returns null inheritkeys [0/1] object ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) the inheritance of keyboard events for the specified object. If 'object' is not specified, then the current object is assumed. When an object is initially created, keyboard inheritance is enabled. returns: nothing see also: object, objtype?, settype, setobjtype inmark? col row buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified column and row position lies within a mark. If 'col' and 'row' are not specified, then the current cursor position is assumed. If 'buffer' is not specified, the current buffer is assumed. returns: The topmost markid containing 'col','row', otherwise null. see also: mark? example: if inmark? then // if cursor is within a mark deleteblock // then delete the mark text else // otherwise.. delchar // delete the char at the cursor end insabove string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts a new line containing the specified string into a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is specified, the new line is inserted before the specified row, otherwise the new line is inserted before the line at the cursor. If 'col' is specified, the string is placed at the specified column, otherwise the string is placed at column one. returns: TRUE if successful, otherwise null. see also: addline, delline, insline, joinline, splitline example: insabove // inserts a new line above the line at the cursor // in the current buffer insabove "New line" 1 6 // inserts a new line with the text " New line" // above line 6 in the current buffer insabove "New line" 1 1 "abc" // inserts a new line with the text "New line" // above line 1 in the buffer "abc" insert? buffer ────────────────────────────────────────────────────────────────────── remarks: Tests if the cursor is in insert or overstrike mode. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if the cursor is in insert mode, otherwise null. see also: setcursor, writetext insertbuf filespec buffer delim/binlen opt=[bxdfhkvqscu] trunc comment linenumber ────────────────────────────────────────────────────────────────────── remarks: Inserts a file or directory into an existing buffer. If 'buffer' is null or not specified, the current buffer is assumed. The file is inserted after 'linenumber'. If 'linenumber' is not specified, then the file is loaded after the current cursor position in the buffer. All other arguments and options are identical to the 'loadbuf' function (see the 'loadbuf' function). returns: The bufferid if successful, otherwise null. see also: asciibuf, createbbuf, createbuf, destroybuf, getloadinfo, loadbuf, menu example: insertbuf "c:\\file.txt" // loads "c:\file.txt" into the current buffer after // the current line in the buffer insertbuf "c:\\file.txt" "abc" 32 'b' '' '' 1000 // loads "c:\file.txt" with a binary line length // of 32, and inserts it after line 1000 of the // buffer "abc" insline string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts a new line containing the specified string into a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is specified, the new line is inserted after the specified row, otherwise the new line is inserted after the line at the cursor. If 'col' is specified, the string is placed at the specified column, otherwise the string is placed at column one. returns: TRUE if successful, otherwise null. see also: addline, delline, insabove, joinline, splitline example: insline // inserts a new line after the line at the cursor // in the current buffer insline "New line" 1 (getlines) // inserts a new line with the text "New line" // after the last line in the current buffer insline "New line" 1 1 "abc" // inserts a new line with the text "New line" // after line 1 in the buffer "abc" instext string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Inserts the specified string into a buffer at the specified row and column. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, then the string is inserted at the current cursor position. returns: TRUE if successful, otherwise null. see also: delchar, ovltext example: instext "some text" // inserts 'some text' at the cursor in the current // buffer instext "some text" 2 20 // inserts 'some text' at column 2, line 20 in the // current buffer instext "some text" 1 1 "abc" // inserts 'some text' at column 1, line 1 in the // buffer 'abc' international dateopt datesep timeopt timesep thousandssep ────────────────────────────────────────────────────────────────────── remarks: Defines international system settings. The following settings can be specified: dateopt - The date format to use [0-2]: 0 = mm dd yy 1 = dd mm yy 2 = yy mm dd datesep - The character used to separate days, months, and years timeopt - The time format to use [0-3]: 0 = 12hr 1 = 24hr 2 = 12hr with seconds 3 = 24hr with seconds timesep - The character used to separate hours, minutes, and seconds thousandssep - The character used to separate thousands groups in large numbers returns: nothing see also: getdate, gettime, thousands joinline col row buffer ────────────────────────────────────────────────────────────────────── remarks: Joins two lines into one line in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. 'row' specifies the first of two lines to be joined, and 'col' specifies the column in the first line where the second line is to be appended. If 'col' is less than or equal to the length of the first line, then the second line is appended to the end of the first line. If 'row' and 'col' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: delline, insabove, insline, splitline example: joinline // joins the line below the cursor to the current line // at the cursor position in the current buffer joinline 1 // appends the line below the cursor to the current line // in the current buffer joinstr delimit+quote string1 string2 ... ────────────────────────────────────────────────────────────────────── remarks: This function joins any number of strings together into an editor 'multistring'. This differs from normal string concatenation in the following ways: - The delimiter character 'delimit' is inserted between the component strings. - The character 'quote' is inserted before any occurrences of the 'delimit' character or the 'quote' character in the resulting string. If the 'delimit' or 'quote' character are not specified, then the default delimiter character is a slash (/) and the default quote character is a backquote (`). returns: a multistring see also: splitstr example: joinstr '' "abc" "def" "xyz" // returns "abc/def/xyz" joinstr '' "abc" "d/ef" "xyz" // returns "abc/d`/ef/xyz" joinstr "|\\" "abc" "x|yz" // returns "abc|x\|yz" justblock opt=[clr] mark leftmarg rightmarg ────────────────────────────────────────────────────────────────────── remarks: Left justifies, right justifies, or centers marked text. If 'mark' is not specified, the default markid is assumed. For column marks, the text is justified to fit between the left and right edges of the mark. For all other marks, the text is justified to fit between 'leftmarg' and 'rightmarg'. One of the following options may be specified: c - center the text l - left justify the text r - right justify the text If no options are specified, then 'l' is assumed. returns: TRUE if successful, otherwise null. see also: formatblock kbdoptions opt=[egw] ────────────────────────────────────────────────────────────────────── remarks: Sets various keyboard options. Any of the following options may be specified: e - enable enhanced keyboard keys g - enable unshifted grey keypad function keys (<grey*>, <grey->, <grey+>) w - enable shifted white keypad function keys (<shift del>, <shift ins>, <shift end>, etc.) returns: nothing keyhit? ────────────────────────────────────────────────────────────────────── remarks: Test if non-shift key has been pressed. returns: TRUE if a key has been pressed and not processed, otherwise null. see also: event?, shiftkey? lastpos buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the last cursor position. If 'buffer' is null or not specified, the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: gotopos left cols buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the left. 'cols' specifies the number of columns to move. If 'cols' is not specified, one is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor column if successful, otherwise null. see also: down, right, up example: left // moves the cursor left 1 column left 5 // moves the cursor left 5 columns lineflag opt=[m-] row buffer ────────────────────────────────────────────────────────────────────── remarks: Turns line flags on or off, or tests if a line flag is turned on. If 'buffer' is null or not specified, the current buffer is assumed. If 'row' is not specified, the line at the cursor is assumed. The following flags can be specified: m - line modified or 'dirty' flag - - turn specified flags off + - turn specified flags on ? - return true if specified flags are on If flags are specified without -, +, or ?, then they will be turned on and any other flags not specified will be turned off. returns: TRUE if '?' is specified with flags that are on, otherwise null see also: bufferflag example: lineflag "-m" // turns off the modified flag for the current buffer listbox title x y buffer width height [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Adds a list box window control to the current dialog box. The listbox window becomes the current window. A list box displays a buffer in scrollable window, allowing a line to be selected from the buffer. The following parameters may be specified: title - the list box title x - the list box x-position in the dialog box y - the list box y-position in the dialog box buffer - the buffer to display in the list box width - the list box width (if not specified, the title width is used) height - the list box height (if not specified, the number of lines in the buffer is used) returns: The group box window id. see also: button, dialog, field, groupbox, whenenter, whenselect example: dialog "Test Dialog Box" 40 17 // create a dialog box listbox "&Listbox:" 3 2 (loadbuf "C:\\*.*") 16 12 // add a list box displaying a directory of drive C getdialog // display the dialog box loadbuf filespec buffer delim/binlen opt=[bxdfhkvqscu] trunc comment ────────────────────────────────────────────────────────────────────── remarks: Loads a file or directory into a new buffer. If 'buffer' is null or not specified, a unique bufferid will be assigned. The new buffer will become the current buffer. The buffer name of the new buffer will automatically be set to 'filespec'. The 'setbufname' function is generally not required (see 'setbufname'). The following options may be specified when loading files: b - load the file in binary mode. The third argument specifies the binary line length. x - disable conversion of fold comments to folds The following options may be specified when loading directories: d - include subdirectories f - include normal files h - include hidden/system files k - shows file sizes in 1k increments q - qualify names with the directory name. This option can only be specified with option 'v'. s - load the directory in 'short' format (name only, starting at column one). This option can only be specified with option 'v'. v - load the directory in variable format c - show names capitalized l - show names in lowercase u - show names in uppercase If options 'c', 'l', or 'u' are not specified, names are shown 'as-is' from the operating system. If option 'b' is specified, the file is loaded in binary mode and the third argument specifies a fixed binary line length. If the third argument is not specified, the default binary line length is 64. If option 'b' is not specified, the third argument specifies a one or two byte line delimiter string to use. If the third argument is not specified, a line delimiter of 0D0Ah (CR/LF) is assumed. The argument 'trunc' specifies the length at which lines are truncated. If 'trunc' is zero or not specified, the editor maximum (16000) is assumed. The argument 'comment' specifies the fold comment string to look for when converting fold comments to text folds during the loading process. Specifying option 'x' disables the conversion. Note: this function will not display the new buffer in a window. The 'openbuf' or 'popup' library functions should be used to display the buffer. returns: The new bufferid if successful, otherwise null. see also: asciibuf, createbbuf, createbuf, destroybuf, getloadinfo, insertbuf, menu, popup, setbufname example: loadbuf "c:\\file.txt" // loads 'c:\file.txt' into a new buffer (using line // delimiter CR/LF) and returns a unique bufferid loadbuf "c:\\file.txt" "abc" // loads 'c:\file.txt' into a new buffer with the // bufferid 'abc' loadbuf "c:\\file.txt" '' (hex2bin "0A") // loads 'c:\file.txt' into a new buffer using line // delimiter '0A' (LF) and returns a unique bufferid loadbuf "c:\\file.txt" '' 25 'b' // loads 'c:\file.txt' into a new binary buffer with // a fixed line length of 25 and returns a unique // bufferid loadobject file object arg3 arg4 ... ────────────────────────────────────────────────────────────────────── remarks: Loads an object from a file. This function is similar to the 'runmacro' function, with the following differences: - the loaded object (macro) automatically remains resident - 'resident ON' is not required. - the loaded object does not initially inherit anything from any other objects. - the current event object is not modified - the objectid is returned returns: the objectid of the loaded object see also: createobject, destroyobject, object, resident, runmacro locase string ────────────────────────────────────────────────────────────────────── remarks: Converts a string to lowercase. returns: the string in lowercase. see also: upcase flipcase example: locase "PEACHES" // returns "peaches" locatefile filespec path opt=[df] ────────────────────────────────────────────────────────────────────── remarks: Searches a path for a filename or directory. 'path' can be a list of paths separated by semicolons (;) (as specified in the Dos 'PATH' environment string). Any of the following options may be specified: d - search for a directory f - search for a file If no options are specified, then 'df' is assumed. returns: the fully qualified filename or directory if found, otherwise null. see also: createdir, directory?, file?, scanfile example: locatefile "file.txt" "c:\\" // returns c:\file.txt, if file.txt is found in c:\ locatefile "file.txt" (getenv "PATH") // returns file.txt (fully qualified), if file.txt is // found in the Dos PATH locatefile "macro" "d:\\aurora" 'd' // returns d:\macro\aurora, if macro is a directory // in d:\aurora lookup variable object ────────────────────────────────────────────────────────────────────── remarks: Gets the value of a public object variable defined by 'variable' in the object defined by 'object'. If 'object' is not specified, the current object is assumed. returns: the value of the object variable if it exists, otherwise null. see also: function?, set, variable? example: lookup "VidCols" lookup "Vid" + "Cols" "prf" lookup myvar // returns the value of an object variable whose // name is the value of 'myvar' machine code arg1 arg2 .. ────────────────────────────────────────────────────────────────────── remarks: Executes machine-level code. This function executes the string specified by 'code' directly as 80x86 machine language code, passing the arguments arg1, arg2 on the stack. The machine code must not contain any external fixups or relocation items - all references must be relative the code itself. The stack size should not be assumed to be larger than 300 bytes. Parameters are passed on the stack from right to left, using the 'C' calling convention. Numbers are passed as long integers (4 bytes), with the high order word pushed first, followed by the low order word. Strings are passed as segment:offset far pointers (4 bytes) to the string contents, with the segment pushed first, followed by the offset. On entry to the machine code, the register ax contains the number of parameters passed, and register bx contains a 'type mask', where each bit indicates the argument type (numeric=0, string=1). For example, if one argument is passed and the first bit of bx is On, then the argument is a string (far pointer), otherwise it is a number (long integer). The machine code is executed with a far call, and therefore must return with a far return. Do not pop any arguments off the stack - this will be done by the machine function. Only register bp must be preserved, if used). returns: a long integer, with the high word equal to register dx and the low word equal to register ax at the time the machine code returns. example: see macro\machine.aml and macro\machine.asm mark? mark ────────────────────────────────────────────────────────────────────── remarks: Tests if a mark exists. If 'mark' is not specified, then the default markid is assumed. returns: TRUE if the mark exists, otherwise null. see also: inmark? markchar startcol endcol toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a character mark. A character mark designates a stream of one or more characters in a buffer. If 'buffer' is null or not specified, the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist, then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'startcol','toprow' to 'endcol','botrow'. If none of these are specified, then the cursor line and column are assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markcolumn, markline, markstream, stopmark example: markchar // marks the character at the cursor using the default // markid and leaves the mark 'open'. markcolumn leftcol rightcol toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a rectangular column mark. If 'buffer' is null or not specified, then the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist, then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'leftcol','toprow' to 'rightcol','botrow'. If none of these are specified, then the cursor line and column are assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markchar, markline, markstream, stopmark example: markcolumn // marks the character at the cursor using the default // markid and leaves the mark 'open'. markcolumn 1 1 1 (getlines) // marks the first column of the entire buffer using // the default markid markline toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a line mark. If 'buffer' is null or not specified, then the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist, then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'toprow' to 'botrow'. If 'toprow' and 'botrow' are not specified, then the line at the cursor is assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markchar, markcolumn, markstream, stopmark example: markline // marks the current line in the current buffer using // the default markid, and leaves the mark 'open' markline 1 (getlines) // marks the entire buffer using the default markid markline '' '' 'T' // marks the current line using the markid 'T' markstream startcol endcol toprow botrow mark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates, extends, or modifies a stream mark. A stream mark designates a stream of zero or more characters in a buffer and does not include 'endcol' on the row 'botrow'. If 'buffer' is null or not specified, then the current buffer is assumed. If 'mark' is not specified, the default markid is assumed. If the mark does not exist, then a new mark is created. If the mark already exists and is not located in the specified buffer, then it is moved there. The mark will be sized to span from 'startcol','toprow' to 'endcol','botrow'. If none of these are specified, then the cursor line and column are assumed and the mark is left 'open' (moving the cursor resizes the mark). If the mark was already open, then it is closed. returns: The markid of the new mark if created, otherwise null. see also: destroymark, extendmark, markchar, markcolumn, markline, stopmark example: markstream // opens a stream mark at the cursor position with the // default markid. Characters will not be marked // until the cursor is moved. max? window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tests if a window is maximized. If 'window' is not specified, the current window is assumed. returns: TRUE if the window is maximized, otherwise null. see also: min? maxems size ────────────────────────────────────────────────────────────────────── remarks: Specifies the maximum amount of EMS memory the editor may use, in 1k increments. If -1 is specified, the maximum available EMS will be used. All available XMS memory will be used before EMS memory is used. Note: this function may only be called once during an edit session. An EMS driver must be installed before EMS memory can be used. returns: Non-zero if successful, otherwise zero. see also: maxxms, memoptions, swapfiles maximize window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Maximizes the specified window. If 'window' is not specified, the current window is assumed. returns: nothing see also: max?, min?, minimize, restore maxxms size ────────────────────────────────────────────────────────────────────── remarks: Specifies the maximum amount of XMS memory the editor may use, in 1k increments. If -1 is specified, the maximum available XMS will be used. Note: this function may only be called once during an edit session. An XMS driver must be installed before XMS memory can be used. returns: Non-zero if successful, otherwise zero. see also: maxems, memoptions, swapfiles memoptions opt=[o] ────────────────────────────────────────────────────────────────────── remarks: Specifies memory usage options. The following options may be specified: o - allows large files to left open (in Dos) after loading, increasing performance when loading large files. returns: nothing see also: maxems, maxxms, swapfiles min? window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tests if a window is minimized. If 'window' is not specified, the current window is assumed. returns: TRUE if the window is minimized, otherwise null. see also: max? minimize window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Minimizes the specified window. If 'window' is not specified, the current window is assumed. returns: nothing see also: max?, maximize, min?, restore mono? ────────────────────────────────────────────────────────────────────── remarks: Tests if the editor is operating in monochrome mode. returns: TRUE if the editor is in monochrome mode, otherwise null. mousepos virtualX virtualY ────────────────────────────────────────────────────────────────────── remarks: Moves the mouse pointer to the specified virtual X and virtual Y coordinates on the screen. returns: nothing see also: getmousex, getmousey, openmouse example: mousepos 16000 16000 // moves the mouse pointer to the upper left // of the virtual screen at startup mousepos 15999 + getvidcols 15999 + getvidrows // moves the mouse pointer to the lower right // of the virtual screen at startup mousesense horz vert doublespeed ────────────────────────────────────────────────────────────────────── remarks: Changes the mouse sensitivity by setting the horizontal mickey-to-pixel and vertical mickey-to-pixel ratios, and by setting the double speed threshold. The default mouse sensitivity after calling 'openmouse' are: Horz mickey-to-pixel ratio: 8 Vert mickey-to-pixel ratio: 16 Double speed threshold: 64 Lower numbers for these parameters result in increased sensitivity. returns: nothing see also: openmouse example: mousesense 5 12 50 // more sensitive mouse moveblock mark buffer col row ────────────────────────────────────────────────────────────────────── remarks: Moves marked text after the specified column and row position in the specified buffer. The text is inserted at the new position and the mark is moved to the new position. If 'mark' is not specified, the default markid is assumed. If 'buffer' is null or not specified, the current buffer is assumed. If 'col' and 'row' are not specified, the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: copyblock, copyblockover movepos (+/-)cols (+/-)rows buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor a relative number of columns and rows away from the current position. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor line number if successful, otherwise null. see also: col, down, gotopos, left, right, row, up example: movepos 2 3 // moves the cursor right 2 columns and down 3 rows movewindow x y opt=[acdrswz1] window relativewindow ────────────────────────────────────────────────────────────────────── remarks: Changes the position of a window. If 'window' is not specified, the current window is assumed. 'x' and 'y' specify the new window coordinates. See the 'sizewindow' function for a description of the coordinates and available options. This call is nearly identical to the 'sizewindow' function, except that only the position of the window can be changed. returns: TRUE if successful, otherwise null. see also: getcoord, sizewindow msgbox message title opt=[b] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window with an 'Ok' button. If a title is not specified, 'Message' is assumed. If option 'b' is specified, the PC speaker beeps. returns: nothing see also: okbox, say, shortbox, yncbox example: msgbox "Hello World" nextfile [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Makes the next buffer in the buffer list the current buffer, and displays it in the current edit window. The buffer previously displayed in the edit window will not be destroyed. returns: nothing see also: filelist, prevfile nexthist [Lib][prompt] ────────────────────────────────────────────────────────────────────── remarks: Displays the next history string in a prompt. This function is only for use within prompts. returns: nothing see also: gethistname, prevhist nextwindow [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Switches the focus to the next window on the screen. returns: nothing see also: prevwindow object? object ────────────────────────────────────────────────────────────────────── remarks: Tests if an object exists. If 'object' is not specified, then the current object is assumed. returns: TRUE if the object exists, otherwise null. see also: destroyobject, object, objtype? objtype? parentobj object ────────────────────────────────────────────────────────────────────── remarks: Tests if the object 'parentobj' is located in the inheritance path of the specified object. If 'object' is not specified, the current object is assumed. returns: TRUE if 'parentobj' is a parent object of 'object', otherwise null. see also: inheritfrom, object, object?, wintype? okbox message title [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window with 'Ok' and 'Cancel' buttons. If a title is not specified, 'Message' is assumed. returns: The name of the button pressed (Ok or Cancel), or null if no button was pressed. see also: msgbox, say, shortbox, yncbox example: if (okbox "Delete the file?" "Delete") == 'Ok' then : end onalarm [Lib] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) when sounding the PC speaker to call attention to a message. This event can be used to customize the alarm sound. 'onalarm' is sent directly to the current event object and is not passed any parameters. returns: none required example: function onalarm // customized alarm sound beep 950 30 beep 750 30 end onclose [Lib] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) when a file or file manager window is closed and removed from memory. 'onclose' is sent directly to the current event object and is not passed any parameters. returns: none required see also: onfocus, onopen, onsave example: see the configuration file Ext.aml onclosedlg button windowid [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) to the dialog box notification object when a dialog box is closed. The button used to close the dialog box is passed as the first argument, and the windowid of the dialog box is passed as the second argument. returns: none required see also: dialog, ondialog oncomment filename comment1 comment2 [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) and extension code (Ext.aml) to retrieve the language comments associated with a filename. 'oncomment' is sent directly to the current event object and is passed the filename as the first argument. 'comment1' and 'comment2' are passed by reference and should be modified within 'oncomment' to return comment symbols. returns: comment1 and comment2 (by reference) example: see Ext.aml. ondesk [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) after the desktop is restored via the restoredesk function. returns: none required ondialog keycode [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) to the dialog box notification object when an unrecognized dialog box key is entered from the dialog box. The keycode of the key as passed as the first argument. returns: none required see also: onclosedlg onentry dosarg1 dosarg2 ... [Lib] ────────────────────────────────────────────────────────────────────── remarks: This event is queued by the editor library (Lib.x) after the default macro file A.x is loaded and executed. 'onentry' is typically used to perform a variety of editor initialization tasks, load Dos command line files, and process user-defined command line options. 'onentry' is queued for execution (not sent directly), and executes in the current event object. Any arguments passed to A.exe on the Dos command line are also passed to 'onentry'. returns: none required see also: onexit example: see the configuration file Ext.aml onexit [Lib] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) when an edit session is ended and control is returned to Dos. This function is typically used to perform a variety of final-exit cleanup tasks. 'onexit' is sent directly to the current event object and is not passed any parameters. returns: none required see also: onentry example: see the configuration file Ext.aml onfocus [Lib] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) after the focus is switched to another file or file manager window. 'onfocus' is sent directly to the current event object and is not passed any parameters. returns: none required see also: onclose, onkillfocus, onopen, onsave onfound stringlength [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) and extension code (Ext.aml) when a string is found in the current buffer. Typically, this function is used to change the window view and/or highlight the string found. 'onfound' is sent directly to the current event object and is passed the length of the string. returns: none required see also: onhotkey example: function onfound (length) : // highlights the string found with the color // white on magenta hilite length 1 95 end onhotkey character [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) and extension code (Ext.aml) when a when a hotkey is entered from the file manager or a file picklist. Typically, this function is used to jump to a file beginning with the hotkey character 'onhotkey' is sent directly to the current event object and is passed the hotkey character. returns: none required see also: onfound onkillfocus [Lib] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) when a window is about to lose the focus. 'onkillfocus' is sent directly to the current event object and is not passed any parameters. returns: none required see also: onfocus onname filespec options [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This event is sent whenever an edit window or file manager window title bar is set, or whenever a filename/filespec needs to be formatted using the NameStyle configuration setting. The onname event handling function returns the formatted filename. The option 't' is passed if the filename is to be displayed on a window title bar. This allows the onname event handling function do optional 'name compression' for long names (i.e. c:\dir\...\file.ext). This event is sent from many locations in Lib.x, Ext.aml, and external macros. The event handling functon for onname is located in Ext.aml. Note that onname is not called for each file in a file manager listing when the listing is initially opened. returns: the formatted name example: see the configuration file Ext.aml onopen options [Lib] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) whenever a new file or file manager window is opened. This event is only sent once when the file is initially opened, or when the file manager window is initially created (not when switching to other files or windows). 'onopen' can be used to perform a variety of initialization tasks on the newly opened file, such as turning on settings based on file extension, altering the position in the file, setting tabs, etc. 'onopen' is sent directly to the current event object after the file or directory is loaded and before the window is displayed. The open options used to open the window are passed to 'onopen'. returns: none required see also: onclose, onfocus, onsave onsave filename [Ext][edit] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor extension code (Ext.aml) immediately before a file is saved. 'onsave' is sent directly to the current event object. The name of the file being saved is passed to 'onsave'. returns: none required see also: onclose, onopen onsyntax filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor library (Lib.x) and extension code (Ext.aml) to retrieve the syntax highlighting object to be associated with a filename. 'onsyntax' is sent directly to the current event object and is passed the filename. 'onsyntax' should return the syntax highlighting object associated with the filename. returns: a syntax highlighting object. example: see Syntax.aml. open filespec opt=[bcefilhnprvz] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Opens the specified file or directory. If a file is specified, then an edit window is opened, otherwise a file manager window is opened. If nothing is specified, then the directory '*.*' is assumed. The following open options may be specified: b - opens the file in binary mode. The binary line length can be specified after the option 'b'. For example, open "file.ext" "b20" In the example above, a file is opened with a binary line length of 20. If a binary line length is not specified, the BinaryLength variable in Config.aml is assumed. c - cascades the window with other windows when loading. e - loads the file into the current edit window. The previous buffer in the window is not destroyed. f - opens the window in 'full-screen' mode (maximized, with all the borders visible). i - inserts the file at the cursor in the current edit window. If a directory is specified, then the user is prompted to select a file. l - specifies the line in the file where the cursor should be placed after loading. The line number is specified after the option 'l'. For example: open "file.ext" "l541" In the example above, a file is opened and the cursor is placed on line 541. h - tiles the window horizontally with other windows on the screen when loading. n - minimizes the window when loading. p - ignores history (the last window and cursor position) when loading the file or directory. This temporarily overrides the SavePosition variable in Config.aml. r - replaces the file in the current window with the new file. The previous buffer in the window is destroyed. v - tiles the window vertically with other windows on the screen when loading. z - maximizes the window when loading. returns: the bufferid of the file or directory if successful, otherwise null. see also: close, openbuf, opennew, reopen, save, setname example: open "c:\\file.txt" // opens the file c:\file.txt open "c:\\file.txt" "pz" // opens the file c:\file.txt in a maximized window, // ignoring history open "d:\\*.txt" 'f' // opens a full-screen file manager window displaying // all files with the extension ".txt" in the root // directory of the D drive. open "c:\\file.txt" "el23" // opens the file c:\file.txt and displays it in the // current edit window. The cursor is placed on // line 23. openbuf buffer opt=[ceflhnprvz] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays an existing buffer in a new edit window. Any open options except 'b' and 'i' may be specified. See the 'open' function for a description of open options. This function allows buffers to be created and manipulated within the editor before being displayed in a window. The buffer should previously have been assigned a buffer name (a fully qualified file name). If the buffer was created with the 'loadbuf' function, the buffer name will have automatically been set to the file name where the buffer was loaded, otherwise the 'setbufname' function should be used to assign a buffer name. returns: nothing see also: close, createbbuf, createbuf, loadbuf, open, opennew, reopen, save, setname example: openbuf (loadbuf "c:\\file.txt") 'z' // load c:\file.txt and display it in a maximized // window buffer = createbuf // create a new buffer if buffer then setbufname "c:\\file.txt" // set the buffer name openbuf buffer // display the buffer end opendesk filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Loads a previously saved desktop from the specified filename and makes it the current desktop. The desktop does not become visible until the 'restoredesk' function is called. returns: Non-zero if successful, otherwise zero see also: begdesk, currdesk, enddesk, restoredesk, savedesk openfile filename opt=[rwc] ────────────────────────────────────────────────────────────────────── remarks: Opens the specified file for reading and/or writing. The following options can be specified: c - create a new file or truncate the file if it already exists r - open the file for reading w - open the file for writing If no options are specified, 'r' is assumed. returns: A file handle if successful, otherwise -1. see also: closefile, filepos, readfile, writefile openhistory filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Opens the specified history file and replaces all existing history buffers with the history in the file. The current desktop is also replaced with the desktop saved in the history file. returns: Non-zero if successful, otherwise null. see also: savehistory openfold opt=[s] row buffer ────────────────────────────────────────────────────────────────────── remarks: Opens a closed fold. If 'buffer' is null or not specified, then the current buffer is assumed. If 'row' is not specified, then the line at the cursor is assumed. If option 's' is specified, all closed subfolds within the fold are also opened. returns: the number of folds opened see also: closefold, createfold, destroyfold, foldblock, getfold example: openfold // opens the closed fold at the current line in the // current buffer, leaving any subfolds closed openkey filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Opens a key macro file saved with the 'savekey' function. If there is a name conflict with any currently defined key macros, the key macros in the opened file will replace the current key macros. returns: TRUE if successful, otherwise null. see also: savekey opennew filename opt=[ceflhnprvz] [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Creates a new buffer and displays it in an edit window. If 'filename' is not specified, the name "New.txt" is assumed. See the 'open' function for a description of valid open options. returns: nothing see also: close, open, openbuf, reopen, save, setname example: opennew "New.c" openmouse opt=[dr] ────────────────────────────────────────────────────────────────────── remarks Initializes the mouse. If successful, the mouse pointer is displayed at the center of the screen and the event queue will process mouse events. For this function to return successfully, a mouse driver such as Mouse.com or Mouse.sys must be installed before the editor is started. Any combination of the following options can be specified: d - hides the mouse pointer when a key is pressed. The mouse pointer is re-displayed when the mouse is used again. r - reverses the mouse buttons returns: TRUE is successful, otherwise null see also: closemouse ovltext string col row buffer ────────────────────────────────────────────────────────────────────── remarks: This function overlays a string onto a buffer at the specified row and column. If 'buffer' is null or not specified, then the current buffer is assumed. If 'col' and 'row' are not specified, then the current cursor position is assumed. returns: TRUE if successful, otherwise null. see also: delchar, instext example: ovltext "some text" // overlays "some text" at the cursor in the current // buffer ovltext "some text" 2 20 // overlays "some text" at column 2, line 20 in the // current buffer ovltext "some text" 1 1 "abc" // overlays "some text" at column 1, line 1 in the // buffer "abc" pagedown (+/-)lines window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in a window down one page, plus or minus the specified number of lines. The default page size is the number of visible rows on the screen minus one row. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. The value of 'lines' is added to the page size. returns: TRUE if successful, otherwise null. see also: pageup example: pagedown // scrolls down one page pagedown 1 // scrolls down one page and one line pagedown -(getviewrows / 2) // scrolls down one half page pageup (+/-)lines window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in a window up one page, plus or minus the specified number of lines. The default page size is the number of visible rows on the screen minus one row. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. The value of 'lines' is added to the page size. returns: TRUE if successful, otherwise null. see also: pagedown example: pageup // scrolls up one page pageup 1 // scrolls up one page and one line pageup -(getviewrows / 2) // scrolls up one half page pan (+/-)cols (+/-)rows ────────────────────────────────────────────────────────────────────── remarks: Pans to a new relative location on the virtual screen by changing the mapping of the physical video device (the screen) to the virtual video device. 'cols' and 'rows' specify the relative distance in screen columns and rows from the current position. returns: TRUE if successful, otherwise null see also: panto example: pan 2 -2 // pans right 2 columns and up 2 rows pankey [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Pans through the virtual screen by using the cursor keys. returns: nothing see also: sizekey panto virtualX virtualY ────────────────────────────────────────────────────────────────────── remarks: Pans to a new absolute location on the virtual screen by changing the mapping of the physical video device (the screen) to the virtual video device. 'virtualX' and 'virtualY' specify an absolute X,Y coordinate on the virtual screen where the upper left corner of the physical screen is to be located. The virtual video device is 64000 x 64000 characters. When the editor is initially invoked, physical screen is placed at 16000,16000 in the virtual screen. returns: TRUE if successful, otherwise null see also: panto example: panto 8000 10000 // pans to column 8000, row 10000 parse searchstr string opt=[irwx] ref1 ref2 ... ────────────────────────────────────────────────────────────────────── remarks: Parses substrings (or substring positions) within a string into local or global variables. This function can be handy for parsing almost any string with only one function call. See the 'pos' function for a description of valid search options. If search option 'x' (regular expressions) is specified, and 'tagged' patterns (enclosed within the {} grouping operators) are specified in the search string, any tagged patterns found are returned in the variables (ref1, ref2, etc.) passed by reference to this function. If search option 'x' is not specified (or tagged patterns are not specified) the positions of successive occurrences of 'searchstr' within 'string' are returned in the variables (ref1, ref2, etc.) passed by reference to this function. returns: The position in the string where the first occurrence of 'searchstr' is found. Substrings (or substring positions) are returned in variables passed by reference to this function. see also: pos, poschar, posnot, sub example: parse "{[0-9]#}.*{[0-9]#}.*{[0-9]#}" str 'x' ref a ref b ref c // parses 'str', and places the first three numbers // found in variables a, b, and c. str = "bacdaae" parse "a" str '' ref x ref y ref z // after this function call: x=2, y=5, z=6 pass arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls the current executing function in the parent object(s) of the current (executing) object, passing the arguments 'arg1', 'arg2', etc. This function can be used to intercept an event or function call for pre-processing or post-processing. returns: The return value from the function call. see also: call, eval, passprev, send, sendobject example: function <lbutton> : // pre-processing : pass // pass control to <lbutton> in a parent object : // post-processing . end passprev arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls the current executing function in the 'preempted' object (if any) of the current object, passing the arguments 'arg1', 'arg2', etc. In all other respects, this function is identical to the 'pass' function. A 'preempted' object is an object which has been temporarily overridden by an object with the same name. The overriding object is defined from within an external macro executed with the 'runmacro' function. Individual functions are temporarily replaced or 'preempted' from within the macro by simply redefining the functions in an object with the same name as the object to be overridden. This allows detailed, temporary modifications to be made to an existing object, without adding new objects to the object hierarchy. The modifications will disappear when the macro is finished executing. This function allows you to access an older overridden or 'preempted' function from within the newer overriding or 'preempting' function. returns: The return value from the function call. see also: call, eval, pass, send, sendobject peek address length ────────────────────────────────────────────────────────────────────── remarks: Gets the portion of Dos memory specified by 'address' and 'length'. The address must be a segment:offset address. The maximum length is 16000. returns: a copy of the specified Dos memory area. see also: poke example: peek 0 100 // returns the first 100 bytes of memory peek 0xb8000000 40 // returns 40 bytes starting at B800:0000 pickfile filespec title title2 bufname sortopt fmgropt [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a file selection menu based on 'filespec'. The following additional parameters can be specified: title - an optional main menu title title2 - an optional right-justified menu title bufname - an optional buffer name to be used for the menu. If a buffer name is specified, the window size and position will be saved and associated with the buffer name. sortopt - one of the following sort options can be specified: d - file date/time (descending) e - file extension n - file name o - Dos default order s - file size (descending) If no options are specified, the FmgrSort variable in Config.aml is assumed. fmgropt - one of the following options can be specified: v - variable length format d - show subdirectories f - show files h - show hidden & system files k - show file sizes in 1k increments 1 - show directories first when sorting by name If no options are specified, the FmgrOpt variable in Config.aml is assumed. returns: The selected file or directory, or null if nothing was selected. see also: popup example: pickfile "c:\\*.*" "Select a file" // displays a file selection menu for the C drive pickfile "c:\\*.*" "Select a file" 's' 'dk' // displays a file selection menu for the C drive, // sorted by file size. The menu will show // subdirectories, and file sizes in 1k increments playkey keyname [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Plays the key macro assigned to the specified key. If 'keyname' is not specified, the current scrap key macro is assumed. returns: TRUE if successful, otherwise null. see also: assignkey, openkey, playing?, savekey, setting example: playkey // plays the current scrap key macro playkey "<ctrl b>" // plays the key macro assigned to <ctrl b> playing? keyname ────────────────────────────────────────────────────────────────────── remarks: Tests if a key macro is currently playing. If 'keyname' is not specified, the current scrap key macro is assumed. returns: nothing see also: assignkey, openkey, playkey, savekey, setting poke address string ────────────────────────────────────────────────────────────────────── remarks: Copies a string to the specified Dos memory address. 'address' must segment:offset address. Obviously, this function should be used with care. returns: nothing see also: peek example: poke 0xb8000000 "T E S T " // copy "T E S T " to B800:0000 popcursor opt=[ad] buffer ────────────────────────────────────────────────────────────────────── remarks: If no options are specified, this function pops a position from the internal cursor stack, and moves the cursor to the popped position. The popped position must have been placed on the stack with the 'pushcursor' function. If 'buffer' is null or not specified, the current buffer is assumed. Any combination of the following options may be specified: a - pops all positions from the cursor stack d - don't move the cursor to the popped position returns: nothing see also: pushcursor pophistory historybuffer title [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a history popup menu for the specified history buffer, with an optional menu title. returns: The string selected from the popup menu. Returns null if nothing was selected or the history buffer does not exist. see also: askhistory example: pophistory "_load" // displays a popup menu for the "_load" history buffer pophistory "_load" "Select a File" // displays a popup menu for the "_load" history buffer // with the title 'Select a File' popup buffer title width height object [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a buffer in a popup menu. If 'buffer' is not specified, the current buffer is assumed. 'buffer' can also be the name of a menu defined with the 'menu' statement. The following parameters can also be specified: title - the popup window title. width - the menu width. If none is specified, and the menu was defined with the 'menu' function, the length of the longest line determines the menu width. height - the menu height. If none is specified, the lesser of the screen rows or the menu rows is assumed. object - the event handling object to be associated with the popup menu (note that this object must be derived from the pre-defined 'popup' object). If specified, the window event handling object for the popup window will be set to this object, allowing for customized keyboard/event behavior. The events 'onopen' and 'onclose' will be sent to the object when the popup menu is opened and closed. If the buffer has been named with 'setbufname', it will remember the previous window and cursor position each time it is displayed. returns: For popup menus defined with the 'menu' statement, the macro expression associated with the menu item is evaluated and the result is returned. If no macro expression is associated with menu item or the menu was not defined with the 'menu' statement, the menu item description line is returned. If no item was selected from the menu, the null string is returned. see also: getmenu, menu, pickfile example: popup "files" "Select a File" // displays the menu buffer 'files' with the title // 'Select a File' popup "files" '' 25 10 // displays the buffer 'files' with no title, // a width of 25 columns, and a height of 10 rows pos searchstr string opt=[irwx] ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string within 'string'. Any of the following search options may be specified: i - ignore case r - search in reverse from the end of the string w - whole words only x - use regular expressions (see Regexp.dox) returns: The position in 'string' where the first occurrence of the search string is found, or zero if nothing is found. see also: parse, poschar, posnot, sub example: pos 'p' "apples" // returns 2 pos 'p' "apples" 'r' // returns 3 pos 'ES' "apples" 'i' // returns 5 poschar charclass string opt=[r] ────────────────────────────────────────────────────────────────────── remarks: Searches for the first character in 'string' which is found in 'charclass'. Character ranges such as 'a-z' or 'A-Z' can be specified. If option 'r' is specified, the search proceeds from the end of string to the beginning of the string. returns: The position in the string where the first character was found, or zero if not found. see also: parse, pos, posnot, sub example: poschar "abc" "123b5a78" // returns 4 poschar "abc" "123b5a78" 'r' // returns 6 poschar "apples" "oranges" // returns 3 poschar "c-f" "oranges" // returns 6 posnot charclass string opt=[r] ────────────────────────────────────────────────────────────────────── remarks: Searches for the first character in 'string' which is not found in 'charclass'. Character ranges such as 'a-z' or 'A-Z' can be specified. If option 'r' is specified, the search proceeds from the end of string to the beginning of the string. returns: The position in the string where the first character not in 'charclass' was found, or zero if not found. see also: parse, pos, poschar, sub example: posnot "abc" "abc123ab" // returns 4 posnot "abc" "abc123ab" 'r' // returns 6 posnot "oranges" "apples" // returns 2 posnot "a-r" "oranges" // returns 7 prevfile [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Makes the previous buffer in the buffer list the current buffer, and displays it in the current edit window. The buffer previously displayed in the edit window will not be destroyed. returns: nothing see also: filelist, nextfile prevhist [Lib][prompt] ────────────────────────────────────────────────────────────────────── remarks: Displays the previous history string in a prompt. This function is only for use within prompts. returns: nothing see also: gethistname, nexthist prevwindow [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Switches the focus to the previous window on the screen. returns: nothing see also: nextwindow printblock device header mark init ────────────────────────────────────────────────────────────────────── remarks: Prints marked text. The text is printed using the printer settings specified with the 'printformat' function. If 'mark' is not specified, the default markid is assumed. All other arguments are identical to the 'printbuf' function (see 'printbuf'). returns: TRUE if successful, otherwise null. see also: printbuf, printformat printbuf device header buffer init ────────────────────────────────────────────────────────────────────── remarks: Prints a buffer. The text is printed using the printer settings specified with the 'printformat' function. If 'buffer' is null or not specified, then the current buffer is assumed. 'device' is the printer device to use. Filenames or device names such as prn, lpt1, lpt2, etc. can be specified. If the device is null or not specified, then prn is assumed. 'header' specifies a string to place on the header and/or footer of each page. Print headers and/or footers must be enabled with the 'printformat' function (see the 'printformat' function). 'init' specifies a device-specific string to send to the the printer before printing. Typically, this string will contain control codes for setting the current font, portrait/landscape orientation, etc. returns: TRUE if successful, otherwise null. see also: printblock, printformat example: printbuf // prints the current buffer to the device 'prn' printbuf "c:\\print.txt" // prints the current buffer to the file 'c:\\print.txt' printbuf "lpt1" "Inventory" "abc" // prints the buffer 'abc' to the device 'prn' using // the header/footer 'Inventory' printformat printer opt=[efhlps] pagesize leftmarg topmarg rightmarg bottommarg linespace copies ────────────────────────────────────────────────────────────────────── remarks: Changes the current printer settings. The following printer settings can be specified: printer - reserved for future use pagesize - specifies the lines per page of printed output. This includes the top margin and the bottom margin. After the specified lines per page have been printed, a formfeed character (Ascii 12) will be sent to the printer and a new page will be started. If 'pagesize' is zero, printing will be continuous (no formfeed characters will be sent to the printer) and 'topmarg', 'bottommarg', and the option 'p' will be ignored. linespace - specifies the number of lines to advance after printing each line of output. A value of 1 generates single-spaced output, 2 generates double-spaced output, and so on. copies - specifies the number of copies to print. topmarg - specifies the number of blank lines to precede printed output at the top of each page. This value is included in 'pagesize'. 'topmarg' is ignored if 'pagesize' is zero. bottommarg - specifies the number of blank lines to follow printed output at the bottom of each page. This value is included in 'pagesize'. 'bottommarg' is ignored if 'pagesize' is zero. leftmarg - specifies the number of blank columns to precede the printed output on each line. rightmarg - specifies the column position at which to truncate each printed line. This column position is relative to column zero of the printed output, not the file being printed. If zero is specified, lines are not truncated. Any of the following print options can also be specified: h - prints a header at the top of each page. The header is specified in the 'printbuf' or 'printblock' functions when printing. This option is ignored if 'pagesize' is zero. f - prints a footer at the bottom of each page. The footer is specified in the 'printbuf' or 'printblock' functions when printing. This option is ignored if 'pagesize' is zero. s - adds a separator line after the header line and before the footer line. p - prints a right justified page number on the header and footer lines. If neither a header or footer was specified, a blank header line is assumed. This option is ignored if 'pagesize' is zero. l - prints a line number at the beginning of each line. e - sends a formfeed character to the printer when printing is completed. returns: nothing see also: printblock, printbuf process ────────────────────────────────────────────────────────────────────── remarks: Creates an editor subprocess by invoking the editor recursively. This function does not return until the 'endprocess' function is called. The effect of this function is equivalent to the following loop: while dispatch do : end returns: nothing see also: dispatch, endprocess purgequeue ────────────────────────────────────────────────────────────────────── remarks: Removes all events from the event queue. returns: nothing see also: queue, queueobject, sizequeue pushcursor buffer ────────────────────────────────────────────────────────────────────── remarks: Saves the cursor position on an internal cursor stack which is unique for each buffer. If 'buffer' is null or not specified, the current buffer is assumed. returns: nothing see also: popcursor qualify filename filespec ────────────────────────────────────────────────────────────────────── remarks: Converts an unqualified or partially qualified filename into a fully-qualified filename, including drive and directory. 'filespec' is used as the 'template' for the qualification. If 'filespec' is not specified, the current drive and path are assumed. returns: a fully qualified filename or directory specification. see also: bootpath, getbootpath example: qualify "file.txt" // returns c:\file.txt if c:\ is the current path qualify "file.txt" "e:\\doc" // returns e:\doc\file.txt queue function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Queues a public function call for later execution. The specified function and arguments 'arg1', 'arg2', etc. are placed on on the event queue. When the editor is idle, it will read the event queue and attempt to call the function in the current event object. returns: TRUE if successful, otherwise null. see also: purgequeue, queueobject, sizequeue example: queue "abc" 1 2 4 // queues the function call 'abc 1 2 4' for later // execution in the current event object queuekey keycode1 keycode2 ... ────────────────────────────────────────────────────────────────────── remarks: Pushes the specified keycodes onto the editor event queue for later execution. returns: nothing see also: geteventcode, getkey, sendkey example: keycode = getkey // gets a keycode... queuekey keycode // and queues it for execution queueobject object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Queues a public function call for later execution in a specific object. The specified object, function, and arguments 'arg1', 'arg2', etc. are placed on the event queue. When the editor is idle, it will read the event queue and attempt to call the function in the specified object. returns: TRUE if successful, otherwise null. see also: purgequeue, queue, sizequeue example: queueobject "edit" "abc" 1 2 4 // queues the function call 'abc 1 2 4' for later // execution in the object 'edit' rand seed ────────────────────────────────────────────────────────────────────── remarks: Generates a random number between 0 and 2147483647. The random number generator can be initialized by specifying a random number 'seed'. Note: the editor library initializes the random number generator with a value based on the current time when the editor is started. returns: a random number. example: rand 12345 // initializes the random number generator rand mod 100 // returns a random number between 0 and 99 readfile length handle ────────────────────────────────────────────────────────────────────── remarks: Reads 'length' characters from the current position in the open file specified by 'handle'. If 'length' is not specified, a length of 16000 is assumed. If a file handle is not specified, then the file handle returned from the most recent openfile call is assumed. The 'length' may not exceed 16000. The current position in the file is advanced by the amount of characters read. returns: The data read from the file if successful, otherwise null. The number of characters actually read from the file can be determined by using the 'length' operator on the returned string. see also: closefile, filepos, openfile, writefile example: // reads the first 100 bytes of file.txt into 'str' if openfile "c:\\file.txt" <> -1 then str = readfile 100 closefile end redo buffer ────────────────────────────────────────────────────────────────────── remarks: Reverses the changes made by the last 'undo' function call for a specific buffer. If 'buffer' is null or not specified, then the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: undo, undobegin, undocursor, undoend renamefile filename newfilename ────────────────────────────────────────────────────────────────────── remarks: Renames the the specified filename to 'newfilename'. A directory can also be renamed to another directory on the same drive. returns: TRUE if successful, otherwise null. see also: copyfile, deletefile reopen filename [Ext][edit_fmgr] ────────────────────────────────────────────────────────────────────── remarks: Reloads the current window with the specified file or directory. If 'filename' is not specified, the buffer name of the current buffer is assumed. The previous file or directory is destroyed. returns: nothing see also: close, fupdate, open, openbuf, opennew, save, setname example: reopen // refreshes the current file from disk reopen "c:\\file.txt" // loads c:\file.txt into the current window, // destroying the existing buffer in the window replace searchstr replacestr opt=[abfgilnorswx*[~] mark buffer ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string within a buffer, mark, or line, and replaces it with 'replstr'. If 'buffer' is not specified, the current buffer is assumed. See the 'find' function for a list of available search options. If option 'a' is specified, all occurrences of the 'searchstr' found will be replaced with 'replacestr'. If option 'a' is not specified, then only the first occurrence of the search string is replaced. If the string is found and neither of the search options 'a' or 'n' are specified, then the cursor is moved to the beginning of the found string, otherwise the cursor does not move. returns: If option 'a' is specified, the number of replacements made is returned, otherwise the length of the replaced string is returned. If nothing is found, then null is returned. see also: find, search example: replace "apples" "oranges" // replaces the next occurrence of 'apples' with // 'oranges' in the current buffer, starting at one // character after the cursor position replace "apples" "oranges" "ag" // replaces all occurrences of 'apples' with 'oranges' // in the current buffer and returns the number of // occurrences. The cursor is not moved. resident [0/1] ────────────────────────────────────────────────────────────────────── remarks: Forces the currently executing macro (invoked by the runmacro function) to remain resident or to be discarded after the macro is finished executing. If 1 is specified, the macro (the object created by runmacro) will remain resident. Any functions or object variables defined in the macro will also remain resident. The macro can be removed later by explicitly destroying the runmacro object with the 'destroyobject' function. If 0 specified, the macro will be discarded (the object created by runmacro will be destroyed). returns: nothing see also: destroyobject, loadobject, runmacro restore window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Restores the specified window. If 'window' is not specified, the current window is assumed. returns: nothing see also: max?, maximize, min?, minimize restoredesk opt=[c] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the current desktop. The current desktop is set by the 'opendesk', 'currdesk', and 'openhistory' functions. The 'begdesk' and 'enddesk' functions also change the current desktop. If option 'c' is specified, the existing desktop is cleared before displaying the new desktop. returns: nothing see also: begdesk, currdesk, enddesk, opendesk, openhistory, savedesk example: opendesk "c:\\desktop.dst" // loads the previously saved desktop in d:\desktop.dst // and makes it the current desktop restoredesk // makes the current desktop visible right cols buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the right. 'cols' specifies the number of columns to move. If 'cols' is not specified, then one is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor column if successful, otherwise null. see also: down, left, up example: right // moves the cursor right 1 column right 5 // moves the cursor right 5 columns rollcol (+/-)cols window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in a window left or right, relative to the current position. If 'window' is not specified, the current window is assumed. The cursor is moved by the same amount that the text scrolls. 'cols' specifies the number of columns to scroll. Positive numbers scroll right and negative numbers scroll left. returns: TRUE if successful, otherwise null. see also: rollrow example: rollcol 4 // scrolls right 4 columns rollcol -1 // scrolls left 1 column rollrow rows window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in window up or down, relative to the current position. If 'window' is not specified, the current window is assumed. The cursor is moved by the same amount that the text scrolls. 'rows' specifies the number of lines to scroll. Positive numbers scroll down and negative numbers scroll up. returns: TRUE if successful, otherwise null. see also: rollcol example: rollrow 4 // scrolls down 4 rows rollrow -1 // scrolls up 1 row row row buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the specified row, but does not change the column. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor line number if successful, otherwise null. see also: col, gotopos example: row 1 // moves the cursor to line 1 in the current buffer row (getlines) // moves the cursor to the last line in the current // buffer runmacro filename object arg3 arg4 ... ────────────────────────────────────────────────────────────────────── remarks: Runs the executable macro contained in the specified filename. The macro is loaded into a new object descended from the current event object, and executed. Arguments passed to the macro are the same arguments passed to the loadobject function. If 'object' is not specified, a unique object name is generated. Normally, when the macro is finished executing, the new object created by runmacro is destroyed and the macro is discarded. However, if the 'resident ON' statement is issued from within the macro, the macro will remain resident until the object is explicitly destroyed with the 'destroyobject' function. returns: The return value from executing the macro. see also: compilemacro, destroyobject, eval, loadobject, resident example: runmacro "c:\\aurora\\macro\\mymacro.x" save filename [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Saves the current buffer to the specified filename. If a filename is not specified, the buffer name of the current buffer is assumed. If the backup setting in the current window is On, the file is backed-up before saving. returns: Non-zero if successful, otherwise zero. see also: close, open, setname, setting, setting? example: save // saves the current buffer to the file name specified // by the name of the buffer save "c:\save.txt" // saves the current buffer to c:\save.txt saveblock filename opt=[abetxz] mark delimiter filedelim comment1 comment2 ────────────────────────────────────────────────────────────────────── remarks: Saves marked text to the specified filename. If 'mark' is not specified, the default markid is assumed. All other arguments and options are identical to the 'savebuf' function (see 'savebuf'). returns: TRUE if successful, otherwise null. see also: loadbuf, savebuf savebuf filename opt=[abetxz] buffer delimiter filedlm comment1 comment2 ────────────────────────────────────────────────────────────────────── remarks: Saves a buffer to the specified filename. If 'filename' is not specified, the buffer name is assumed. If 'buffer' is null or not specified, then the current buffer is assumed. The following options may be specified: a - append to end of the file when saving b - save the file in binary mode, with no line delimiters e - entab the buffer while saving. The tabwidth is specified after the 'e' option - for example: 'e8'. t - trim trailing blanks and tabs from each line x - disable conversion of folds to fold comments z - append ctrl-z (Ascii 26) to the end of the file when saving 'delimiter' specifies a one or two byte line delimiter string to be appended to the end of each line in the saved file. If 'delimiter' is null or not specified, then the line delimiter used when loading the file is assumed. If the buffer was not loaded but created new, then a line delimiter of 0D0Ah (CR/LF) is assumed. 'filedlm' specifies an alternate one byte file delimiter to save at the end of the file. 'comment1' and 'comment2' specify the opening and closing comment strings to be used when converting text folds to fold comments during the saving process. Specifying option 'x' disables the saving of folds as fold comments. returns: TRUE if successful, otherwise null. see also: createbbuf, createbuf, destroybuf, loadbuf, saveblock example: savebuf "c:\\file.txt" // saves the current buffer to the file 'c:\file.txt', // and overwrites any previous data in the file. // The file is saved with CR/LF line delimiters. savebuf "c:\\file.txt" 'b' "abc" // saves the buffer 'abc' to 'c:\file.txt' in binary // mode, with no line delimiters savebuf "c:\\file.txt" 't' '' (hex2bin "0A") (char 0) // saves the current buffer to 'c:\file.txt' and // trims trailing blanks from each line. The file // is saved with '0A' (LF) line delimiters and a // file delimiter of Ascii 0. savedesk filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Saves the current desktop to the specified filename. The current desktop is set by the 'opendesk', 'currdesk', and 'openhistory' functions. The 'begdesk' and 'enddesk' functions also change the current desktop. returns: TRUE is successful, otherwise null. see also: begdesk, currdesk, enddesk, opendesk, restoredesk example: currdesk // set current desktop to the current window layout savedesk "c:\\desktop.dst" // save the current desktop to c:\desktop.dst savehistory filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Saves all existing history buffers and the current desktop to the specified filename. returns: TRUE if successful, otherwise null. see also: openhistory savekey filename [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Saves all current key macros to the specified filename. The key macros can be reloaded later with the 'openkey' function. returns: TRUE if successful, otherwise null. see also: openkey say message opt=[b] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message at the location of the primary title (title 1) of the current window. If option 'b' is specified, the PC speaker beeps. The message is cleared the next time the display is updated. returns: nothing see also: msgbox, okbox, shortbox, yncbox example: say "Hello World" scanfile filename searchstr opt=[iwx] delimiter ────────────────────────────────────────────────────────────────────── remarks: Scans the specified filename for the string 'searchstr'. 'delimiter' specifies the line delimiter used to separate lines in the file. If 'delimiter' is not specified, then CR/LF (0D0Ah) is assumed. Any of the following options may be specified: i - ignores case during the scan w - scans for whole words only x - checks for regular expression chars in the search string (see Regexp.dox) returns: The absolute position in the file where the search string was found (starting with one), or zero if not found. If the scan was interrupted by <ctrl break>, then zero is returned. see also: find, replace example: scanfile "c:\\file.txt" "apples" "i" // returns the first position in c:\file.txt where // 'apples' is found (ignoring case), or zero if // not found scrollcol column window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in window so that 'column' is the leftmost column in the window. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. returns: TRUE if successful, otherwise null. see also: scrollrow example: scrollcol 4 // scrolls the current window so that the leftmost // column in the window is 4. The cursor moves // accordingly. scrollrow row window ────────────────────────────────────────────────────────────────────── remarks: Scrolls the text in window so that 'row' is the topmost line in the window. The cursor is moved by the same amount that the text scrolls. If 'window' is not specified, the current window is assumed. returns: TRUE if successful, otherwise null. see also: scrollcol example: scrollrow 4 // scrolls the current window so that the topmost // line in the window is 4. The cursor moves // accordingly. search searchstr/replstr/options reverse repeat [Ext][a] ────────────────────────────────────────────────────────────────────── remarks: Searches for the specified search string in the current buffer, and optionally replaces it with 'replstr'. This function provides a higher level interface to the 'find' and 'replace' builtin functions. The parameters 'searchstr/replstr/options' are entered together as one argument in multi-string format (see the 'joinstr' and 'splitstr' functions). If no search options are explicitly specified, the variables SearchOpt and ReplaceOpt in Config.aml are assumed. See the 'find' function for a description of valid search options. If 'replstr' is specified and option 'a' (replace all) is not specified, the editor will prompt for each replacement. If 'reverse' is 'r', then the search proceeds in the reverse direction from the direction specified in the search options. If 'repeat' is TRUE, then search option 'g' (global search) will be ignored if specified. returns: The same values as the 'find' and 'replace' builtin functions, depending on the action performed (find or replace) and the search options specified (see the 'find' and 'replace' functions). see also: find, findlast, joinstr, replace, splitstr example: search "apples" // searches for the string 'apples' (case sensitive) // starting at one char to the right of the cursor // and searching toward the end of the buffer search "apples/ir*" // searches for 'apples' (case insensitive) starting at // the cursor position and searching toward the // beginning of the buffer search "app'/les/bgw" // searches for 'app/les' (whole words only), limiting // the search to the current mark and starting from // the beginning of the mark search "apples/oranges/ag" // replaces all occurrences of 'apples' with 'oranges' // in the current buffer and returns the number of // occurrences. The cursor is not moved. send function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls a public function in the current event object whose name is the value of 'function', passing the optional arguments 'arg1', 'arg2', etc. returns: The return value from calling the specified function. see also: call, eval, pass, sendkey, sendobject example: send <ctrl b> // simulates <ctrl b> send '<' + "ctrl b" + '>' // simulates <ctrl b> sendkey keycode1 keycode2 ... ────────────────────────────────────────────────────────────────────── remarks: Executes the specified keycodes immediately and synchronously, in the current event object. returns: nothing see also: geteventcode, getkey, queuekey, send, sendobject example: keycode = getkey // gets a keycode... sendkey keycode // and executes it immediately sendobject object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Calls a public function in the specified object whose name is the value of 'function', passing the optional arguments 'arg1', 'arg2', etc. returns: The return value from calling the specified function. see also: call, eval, pass, send, sendkey example: sendobject "edit" <ctrl b> sendobject "edit" '<' + "ctrl b" + '>' set variable value object ────────────────────────────────────────────────────────────────────── remarks: Assigns a value to a public object variable in the specified object. If an object is not specified, the current object is assumed. If the variable does not already exist, then it is created. returns: nothing see also: destroyvar, lookup, setfunction, variable? example: set "Two" 2 set "number" 1 + 2 + x - 4 set "TabWidth" 4 "edit" setalarm timerid year mon day dayofweek hour min second object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets a timer to call 'function' automatically at the specified date and time. If -1 is specified for for any of the date or time parameters, the timer will call the function for any value of that parameter (the parameter becomes a 'wildcard'). If -1 is specified for any of the arguments, the timer is a 'repeating' timer and is not destroyed, otherwise the timer is automatically destroyed after the function call. The function is called in the specified object, passing the optional arguments 'arg1', 'arg2', etc. If 'object' is not specified, the current event object is assumed. 'timerid' uniquely identifies the timer. If a timerid is not specified, a unique timerid is generated. A maximum of 16 timerid's may be active at one time. returns: The timerid if successful, otherwise null. see also: destroytimer, setrepeat, settimer, timer? example setalarm "xyz" // timerid 'xyz' -1 // any year -1 // any month -1 // any day -1 // any day of the week 22 // 10 o'clock at night 0 // zero minutes 0 // zero seconds '' // send to current event object "abc" // function 'abc' // the above example sets timer 'xyz' to call the function // 'abc' at 10 o'clock every night in the current event // object setbook bookmark buffer ────────────────────────────────────────────────────────────────────── remarks: Creates a new bookmark or modifies an existing bookmark. The bookmark is placed at the current cursor position in the specified buffer. If the buffer is null or not specified, the current buffer is assumed. returns: The bookmarkid if a bookmark is created, or TRUE if an existing bookmark is modified, otherwise null. see also: destroybook example: setbook 'A' // places bookmark 'A' at the cursor position setbootpath path ────────────────────────────────────────────────────────────────────── remarks: Changes the editor 'boot' path for the current session. returns: nothing see also: bootpath, getbootpath setborder opt=[ios012345] xd yd cornerX cornerY bchr1 bchr2 bchr3 window ────────────────────────────────────────────────────────────────────── remarks: Changes the border style of a window. If 'window' is not specified, the current window is assumed. The window must first be configured to allow borders by calling the 'setframe' function. The following parameters can be specified: xd - left and right border thickness yd - top and bottom border thickness cornerX - amount or horz overlap on the border corners cornerY - amount or vert overlap on the border corners bchr1 - border fill character bchr2 - border corner fill character bchr3 - hex view divider character The following options can also be specified: i - inward 3D effect o - outward 3D effect s - attempts to change the size of other parts of the window to accommodate the new border style, without changing the overall size of the window. 0 - use 'expanded' borders (the default) For the following options, the 'xd', 'yd', 'cornerX', and 'cornerY', 'bchr1', and 'bchr2' parameters are ignored, and the horizontal and vertical border thickness is always one: 1 - single line 2 - double horizontal 3 - double vertical 4 - double line 5 - solid 6 - blank Specifying no options or parameters removes any existing borders. returns: nothing see also: getborder, setframe, setshadow example: setborder // removes the border setborder "1i" // sets the border style to a single-line border with // an inward 3D effect setborder '0' 2 2 3 3 // sets the border style to an 'expanded' border with // border width 2 and corner size 3 setbufname name buffer ────────────────────────────────────────────────────────────────────── remarks: Associates a descriptive name with a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. The buffer name is used by editor library functions to identify the current buffer, and is usually a fully qualified file name. Note: the 'loadbuf' function will automatically set the buffer name to the file name where the buffer was loaded ('setbufname' is not required). returns: nothing see also: getbufname setbuftabs tabwidth buffer ────────────────────────────────────────────────────────────────────── remarks: Sets the tab width used for displaying real tabs. If 'buffer' is not specified, the current buffer is assumed. If the tabwidth is zero, then real tabs are displayed as-is (Ascii 9). Note that this function will also clear the undo/redo stack. returns: nothing see also: getbuftabs, undo, redo setcolor component color window ────────────────────────────────────────────────────────────────────── remarks: Changes the color attribute of a window component. If 'window' is not specified, the current window is assumed. The following values can be specified for 'component': 0 - border 1 - border corners 2 - north and east titles 3 - south and west titles 4 - title bar controls 5 - text 6 - marks 7 - scroll bars 8 - menus 9 - menu character highlight 10 - menu disable 11 - menu bar highlight 12 - end-of-text line 13 - border highlight color 14 - folds 15 - modified lines 16 - modified line at the cursor 17 - open fold begin 18 - open fold end returns: nothing see also: getcolor example: setcolor 5 95 // sets the window text color to white on magenta setcolor 6 32 // sets the mark default color to black on green setcursor opt=[rhiv+-] cursor buffer ────────────────────────────────────────────────────────────────────── remarks: Creates a new cursor or changes the state of an existing cursor. If 'buffer' is null or not specified, then the current buffer is assumed. If 'cursor' is not specified, the current cursor is assumed. If 'cursor' refers to an existing cursor, it is modified according to the options specified, otherwise a new cursor is created. If a new cursor is created, it becomes the current cursor. Any of the following options may be specified: i - cursor is in insert mode h - cursor is hidden v - blinking hardware cursor indicates position - - turns off any specified options + - turns on any specified options returns: The cursorid if a cursor is created, or TRUE if an existing cursor is modified successfully, otherwise null. see also: cursor?, destroycursor setdisplay [-1/0/1] ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) updating of the display. Note that any operations involving window sizing, movement, or reordering will still update the display, even if the display is disabled with this function. If -1 is specified, the display is 'validated' and the next screen update will be skipped. This allows you to draw on the text in an Edit or File Manager window, leaving your changes visible until the following screen update. returns: nothing see also: display example: setdisplay OFF // disable display for faster execution playkey // play the scrap key macro setdisplay ON // enable the display writestr "Hello" // write 'Hello' in an edit window setdisplay -1 // allow it to remain visible setdraw opt=[01234] window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Changes the line drawing style for an edit window. If 'window' is not specified, the current window is assumed. One of the following options can be specified: 0 - single lines 1 - double horizontal lines 2 - double vertical lines 3 - double horizontal and vertical lines 4 - eraser returns: nothing see also: setting example: setdraw 3 // sets the line drawing style to double horizontal // and vertical lines seterror errorcode errorstring ────────────────────────────────────────────────────────────────────── remarks: Generates an AML compiler error with the specified error code when called from within a constant function or #exec-#endexec block at compile-time. Any error code can be specified, including new user-defined errorcodes. Both the errorcode and errorstring (if specified) can be retrieved later via the 'geterror' function. This function can be useful in checking for any number of user-defined error conditions at compile time, such as invalid arguments passed to a constant function, required files or resources not found, etc. returns: nothing see also: geterror seteventobj object ────────────────────────────────────────────────────────────────────── remarks: Changes the current event object to the specified object. The current event object is the object where events are dispatched by the editor. If 'object' is not specified, the current (executing) object is assumed. Note: if a window has been associated with an event object via the 'setwinobj' function, the current event object is automatically changed to the window object when the window becomes the current window. returns: TRUE if successful, otherwise null. see also: geteventobj, setwinobj setfileattr filename attributes=[ahrs] ────────────────────────────────────────────────────────────────────── remarks: Changes the attributes of the file 'filename'. Any of the following attributes can be specified: a - archive h - hidden r - read-only s - system null - no attributes returns: Non-zero if successful, otherwise zero. see also: fileattr? example: setfileattr "c:\\file.txt" 'r' // makes c:\\file.txt a read-only file setframe opt=[bwneshvm2345z>+-] window westwidth eastwidth ────────────────────────────────────────────────────────────────────── remarks: Adds or removes window frame components. If 'window' is not specified, the current window is assumed. Any of the following options can be specified: + - add specified components to the window - - remove specified components from the window (if neither '+' or '-' are specified, then the window frame components are replaced) b - border e - east title bar h - horizontal scroll bar m - primary menu bar n - north title bar s - south title bar v - vertical scroll bar w - west title bar z - south title controls 2 - menu bar 2 (north) 3 - menu bar 3 (north) 4 - menu bar 4 (south) 5 - menu bar 5 (west) > - place north title bar in the window border (for bordertype > 0) < - place south title bar in the window border (for bordertype > 0) Specifying no options will remove all window frame components. The following parameters can also be specified: westwidth - the width of the west title, if present eastwidth - the width of the east title, if present returns: nothing see also: frame?, setborder, setshadow example: setframe // removes all frame components from the current window setframe "bn" // replaces the current window frame components with // a border and a north title bar setframe "+s" // adds a south title bar to the current window setfunction function expression object ────────────────────────────────────────────────────────────────────── remarks: Changes the definition of a public function in the specified object to the macro source code in the string 'expression'. If an object is not specified, the current object is assumed. If the function does not already exist, then it is created. This statement can be used to change the definition of a function at run-time. returns: nothing see also: destroyvar, function?, lookup, set example: setfunction "<ctrl d>" "beep 400 400" "edit" // assigns the macro code 'beep 400 400' to <ctrl d> // in the object 'edit' setgroupbox initvalue valuemap window [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Re-initializes the checked/unchecked state of check boxes and radio buttons in a group box, after the group box has already been created. If 'window' (the group box window id) is not specified, the current window is assumed. See the 'group' function for a description of 'initvalue' and 'valuemap'. returns: nothing see also: dialog, group, whenenter, whenselect setname filename [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Changes the buffer name in the current edit window to the specified filename. The primary window title (title 1) is also changed. returns: 1 if successful, -1 if the filename is invalid, or -2 if the filename is already loaded. see also: close, open, save, setbufname, settitle setnextwin nextwindow window ────────────────────────────────────────────────────────────────────── remarks: Changes the order of windows on the screen by placing 'nextwindow' on top of 'window'. If 'window' is not specified, the current window is assumed. returns: Non-zero if successful, otherwise null. see also: getnextwin, getprevwin, setprevwin setobjtype object parentobj1 parentobj2... ────────────────────────────────────────────────────────────────────── remarks: Sets the inheritance path of the specified object to parentobj1, parentobj2, etc. After this function is called, the specified object will inherit functions and object variables from parentobj1, parentobj2, etc. returns: nothing see also: inheritkeys, object, objtype?, settype setpalette position charstring ────────────────────────────────────────────────────────────────────── remarks: Fills a 100-byte user-defined color palette area with 'charstring', starting at the specified position in the palette. The editor library code (Lib.x) expects color attributes to be in the positions defined in Color.aml. returns: nothing see also: getpalatte example: see Color.aml setparent parent window ────────────────────────────────────────────────────────────────────── remarks: Makes 'parent' the parent window of 'window'. If 'window' is not specified, the current window is assumed. returns: Non-zero if successful, otherwise null. see also: getparent setprevwin prevwindow window ────────────────────────────────────────────────────────────────────── remarks: Changes the order of windows on the screen by placing 'window' on top of 'prevwindow'. If 'window' is not specified, the current window is assumed. returns: Non-zero if successful, otherwise null. see also: getnextwin, getprevwin, setnextwin setrepeat timerid milliseconds object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets a timer to call 'function' automatically at regular intervals. 'milliseconds' specifies the time interval in milliseconds. The first function call will occur after the specified time interval has expired (not after the 'setrepeat' call). The function is called in the specified object, passing the optional arguments 'arg1', 'arg2', etc. If 'object' is not specified, the current event object is assumed. 'timerid' uniquely identifies the timer. If a timerid is not specified, a unique timerid is generated. A maximum of 16 timerid's may be active at one time. returns: The timerid if successful, otherwise null. see also: destroytimer, setalarm, settimer, timer? example: setrepeat "xyz" 1000 '' "abc" // sets timerid 'xyz' to call the function 'abc' every // second in the current event object setrepeat "t1" 0 '' "idle" // sets timerid 't1' to call the function 'idle' // repeatedly in the current event object whenever // the editor is idle setshadow right bottom window ────────────────────────────────────────────────────────────────────── remarks: Adds or removes window shadows. If 'window' is not specified, the current window is assumed. 'bottom' and 'right' specify the shadow thickness on the bottom and right borders. If 'bottom' and 'right' are zero or null, the shadow is removed. returns: nothing see also: setborder, setframe, setshadow2 example: setshadow // removes any shadows from the current window setshadow 2 1 // sets the shadow thickness to 2 on the right border // and 1 on the bottom border setshadow2 color window ────────────────────────────────────────────────────────────────────── remarks: Adds or removes a one-half width shadow. If 'window' is not specified, the current window is assumed. 'color' specifies the shadow color. This function is intended for use with stationary windows on a blank background (such as dialog box controls). returns: nothing see also: setshadow setsyntax [0/1] object window ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) syntax highlighting for a window. If 'window' is not specified, the current window is assumed. Specifying 'object' will change the syntax highlighting object associated with the window. returns: nothing see also: getsyntax, keyword settimer timerid milliseconds object function arg1 arg2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets a timer to call 'function' automatically after a specified time interval. 'milliseconds' specifies the time interval in milliseconds. The timer is automatically destroyed when the function is called. The function is called in the specified object, passing the optional arguments 'arg1', 'arg2', etc. If 'object' is not specified, the current event object is assumed. 'timerid' uniquely identifies the timer. If a timerid is not specified, a unique timerid is generated. A maximum of 16 timerid's may be active at one time. returns: The timerid if successful, otherwise null. see also: destroytimer, setalarm, setrepeat, timer? example: settimer "xyz" 1000 '' "abc" // sets timerid 'xyz' to call the function 'abc' one // second later in the current event object setting settings [0/1/2/-1] object [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Changes or toggles the specified window settings. Any combination of the following settings may be specified: a - Autoindent b - Backup d - Draw mode h - Hex view i - Insert mode l - Live Word Wrap m - Match Character s - Smart tabs t - Translate u - Undo enabled v - Variable tabs w - Word Wrap (standard) x - Syntax Highlighting If setting 'x' is turned on, 'object' defines the syntax highlighting object to use. If 'object' is not specified, the 'onsyntax' event is sent to obtain the syntax highlighting object. After the 'settings' argument, one of the following values can be specified: 0 - turns specified settings Off 1 - turns specified settings On -1 - toggles specified settings 2 - sets specified settings to default values An object may be specified returns: nothing see also: getsettings, setting? example: settings "abu" 1 // turns On autoindent, backup, and undo settings "xd" 0 // turns Off syntax highlighting and drawmode settings "w" -1 // toggles word wrap setting? settings [Lib][mon] ────────────────────────────────────────────────────────────────────── remarks: Tests if any of the specified window settings are On. See the 'setting' command for a description of window settings. returns: Non-zero if one of the specified settings is On, otherwise null. see also: getsettings, setting example: setting? "lw" // tests if word wrap or live word wrap are On settitle string opt=[nsewlcrdxh1z] titleid[1-5] window ────────────────────────────────────────────────────────────────────── remarks: Changes a window title. If 'window' is null or not specified, then the current window is assumed. Each window can have up to 5 titles. 'titleid' (1-5) specifies the window title to change. If the 'titleid' is null or not specified, then 1 (the primary title) is assumed. Any combination of the following options can be specified: e - places the title on east title bar n - places the title on north title bar s - places the title on south title bar w - places the title on west title bar l - left justifies the title c - centers the title r - right justifies the title d - redraws the window title immediately after this function call x - sets the title to the 'default status line'. The status line displays information about the buffer (if any) displayed in the window. h - checks for the highlight character "&". Specifying "&" before a character in the title indicates that the character is to be highlighted. 1 - the title is not padded with spaces. Normally the title is padded with one space if it is left or right justified. z - hides the title. This can be used to associate a string with a window by storing it as a hidden window title, and should be used when specifying a title for the end-of-text line (see the 'eotstring' function). If no options are specified, and the title has not been previously set, the options 'nl1' are assumed. If the title has been previously set, then the options of the previous title are assumed. returns: TRUE if successful, otherwise null. see also: eotstring, gettitle example: settitle "Hello World" // sets window title 1 to 'Hello World' settitle "Hello World" "cs" 3 // sets window title 3 to 'Hello World' and // centers it on the south title bar settype parentobj parentobj2 ... ────────────────────────────────────────────────────────────────────── remarks: Sets the inheritance path of the current object to parentobj1, parentobj2, etc. After this function is called, the current object will inherit functions and object variables from parentobj1, parentobj2, etc. returns: nothing see also: inheritkeys, object, objtype?, setobjtype example: settype "win" // the current object now inherits functions and // object variables from the object 'win' setvideo cols rows color fillstring ────────────────────────────────────────────────────────────────────── remarks: Changes the video mode and/or sets the background color attribute and background fill string. Either operation can be done separately or simultaneously. When changing the video mode, 'cols' must be 40 or 80 and 'rows' must be 12, 14, 21, 25, 28, 43, or 50. If 'cols' or 'rows' are zero or null, the video mode is not changed. Specifying either 'color' or 'fillstring' changes the video background. If 'color' is not specified, black (0) is assumed. If 'fillstring' is not specified, blanks are assumed. The maximum size of 'fillstring' is 50 characters. returns: TRUE if successful, otherwise null. see also: videomode setwinctrl controlstring rightcontrol window ────────────────────────────────────────────────────────────────────── remarks: Changes the one-character title bar controls for a window. If 'window' is not specified, the current window is assumed. Controls are normally placed on the north title bar unless south title bar controls are specified with the 'setframe' function. 'controlstring' is a string of the one-character title bar controls to appear on the title bar from left to right. By default, controls are left justified on the title bar. If specified, 'rightcontrol' defines the character position in 'controlstring' of the first right justified control. returns: TRUE if successful, otherwise null. see also: getwinctrl example: setwinctrl "" // places one left justified control () on the // title bar setwinctrl "≡" 2 // places 3 controls on the title bar. (≡) is // left justified, () and () are right justified setwincurs cursor window ────────────────────────────────────────────────────────────────────── remarks: Attaches a cursor to a window and associates a buffer with a window. If 'window' is not specified, the current window is assumed. When a cursor is attached to a window, the window will display the buffer associated with the cursor. If 'cursor' is null or not specified, then the cursor is detached from the window and the window will no longer display a buffer. Only one cursor may be associated with a window at one time. Windows that do not display a buffer do not need to use this call. returns: TRUE if successful, otherwise null. see also: getwincurs setwinobj object window ────────────────────────────────────────────────────────────────────── remarks: Sets the window event object associated with a window. If 'window' is not specified, the current window is assumed. This function also changes the current event object to 'object'. Whenever a window becomes the current window, the current event object is set to the window event object. This allows an object 'class' to be associated with an individual window. returns: nothing see also: getwinobj, seteventobj example: setwinobj "edit" // sets the event object for the current window to // 'edit', and also changes the current event object // to 'edit' shiftblock (+/-)cols mark fillchar ────────────────────────────────────────────────────────────────────── remarks: Shifts marked text to the left or to the right. If 'mark' is not specified, the default markid is assumed. 'cols' specifies the number of columns to shift. Positive values shift text to the right and negative values shift text to the left. 'fillchar' is the character to use when filling empty spaces created by shifting to the right. If 'fillchar' is not specified, blanks (Ascii 32) are assumed. returns: TRUE if successful, otherwise null. see also: delchar, instext example: shiftblock -1 // shifts the text in default markid one space to the // left shiftblock 1 '' '>' // shifts the text in the default markid one space to // the right, filling empty spaces with '>' shiftkey? shiftstate ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified shift key(s) are currently pressed down. 'shiftstate' can be any combination of the following values bitwise-ORed together: 01h - right shift key down 10h - scroll lock On 02h - left shift key down 20h - num lock On 04h - ctrl key down 40h - caps lock On 08h - alt key down 80h - insert On If shiftstate is not specified, then a value of 03h (right and left shift keys) is assumed. returns: Non-zero if the specified shift keys are down, otherwise zero. see also: event?, keyhit? example: shiftkey? // tests if the left or right shift keys are pressed shiftkey? 12h // tests if the <ctrl> or <alt> keys are pressed shortbox message title opt=[b] [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window without an 'Ok' button. If a title is not specified, 'Message' is assumed. If option 'b' is specified, the PC speaker beeps. returns: nothing see also: msgbox, okbox, say, yncbox example: shortbox "This is a message with a beep!" 'b' showcursor top bottom ────────────────────────────────────────────────────────────────────── remarks: Shows the physical cursor in the current window. If the current window contains a buffer, the effects of this function are temporary and may disappear the next time the display is updated. If 'top' and 'bottom' are specified, the physical cursor size is changed. 'top' and 'bottom' indicate the distance of the top and bottom of the cursor from the top of the character cell, on a scale of 0 to 99. returns: nothing see also: hidecursor example: showcursor 0 99 // sets the cursor size to fill the entire char cell showcursor 50 99 // sets the cursor size to fill the bottom half of // the character cell showdialog [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Tags the current dialog box as a 'modeless' dialog box. The dialog box will function as an independent window on the desktop (existing windows on the screen can be placed on top of a modeless dialog box). This function returns immediately, without actually displaying the dialog box. The 'whenenter' and 'whenselect' functions can be used to process events from dialog box controls. returns: nothing see also: dialog, getdialog, whenenter, whenselect example: dialog "Test Dialog Box" 40 8 button "O&k" 17 2 8 // tag the dialog box as modeless showdialog showentry ────────────────────────────────────────────────────────────────────── remarks: Temporarily displays the screen as it appeared in Dos immediately before the editor was started. Pressing any key or mouse button will restore the editor screen. returns: nothing see also: display showmouse ────────────────────────────────────────────────────────────────────── remarks: Shows the mouse pointer. returns: nothing see also: hidemouse showwindow window ────────────────────────────────────────────────────────────────────── remarks: Re-displays a window that was previously hidden with the 'hidewindow' function. If 'window' is null or not specified, then the current window is assumed. returns: nothing see also: hidewindow sizekey [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Resizes the current window using the cursor keys. returns: nothing see also: pankey, sizewin sizequeue size ────────────────────────────────────────────────────────────────────── remarks: Removes all events from the event queue and changes the event queue size to 'size' events. Values of 5 through 200 may be specified. The default queue size is 20 when the editor is started. returns: Non-zero if successful, otherwise zero. see also: dispatch, process sizewin l t r b reps opt=[acdrswz1] window [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Resizes the specified window. If 'window' is not specified, the current window is assumed. This function is nearly identical to the 'sizewindow' builtin function, except that the window title bar controls are set properly after resizing, and 'reps' (sizing repetitions) can be specified. returns: nothing see also: movewindow, sizewindow sizewindow l t r b opt=[acdrswz1] window relativewindow ────────────────────────────────────────────────────────────────────── remarks: Changes the size and position of a window. If 'window' is not specified, the current window is assumed. When a window is resized, all parts of the window are redrawn immediately. 'l', 't', 'r', and 'b' specify the new window coordinates. The following options can be specified: a - The coordinates are absolute and are based at an 'origin'. The location of the origin depends on which of the following options are also specified: d - the origin is located at the top left corner of the physical screen w - the origin is located at the top left corner of the window 'relativewindow' 1 - the origin is located at the top left corner of the client area of the window 'relativewindow' z - the origin is located at the virtual coordinates (0,0) If option 'a' is specified and none of the above options are specified, then 'd' is assumed. r - the coordinates are relative to another rectangle on the screen. 'l', 't', 'r', and 'b' specify relative offsets from the left, top, right, and bottom edges of the rectangle. The location of the rectangle depends on which of the following options are also specified: d - the rectangle is the physical screen w - the rectangle is the main window area of the window 'relativewindow' 1 - the rectangle is the client area of the window 'relativewindow' z - the rectangle is the main window area of the window being resized (relative to itself, in other words) If option 'r' is specified and none of the above options are specified, then 'z' is assumed. c - the coordinates specify the size of the client area of the window being sized, not the entire window. s - scrolls the window to keep the cursor visible, if needed If no options are specified, options 'rz' are assumed. returns: TRUE if successful, otherwise null. see also: getcoord, movewindow example: sizewindow -1 -1 1 1 // expands the current window size by 1 in all four // directions sizewindow 0 0 0 0 "rd" // sizes the current window to fill the entire screen // with all the borders visible sizewindow 6 5 72 20 "ad" // sizes the current window relative to the upper // left corner of the screen sizewindow 6 5 72 20 "a1" '' "abc" // sizes the current window relative to the upper // left corner of the client area of window 'abc' sortblock opt=[di] mark column ────────────────────────────────────────────────────────────────────── remarks: Sorts marked lines. If 'mark' is not specified, the default markid is assumed. For column marks, the text between the left and right edges of the mark is used as the sort key. For line marks, the text between 'column' and the end of the line is used as the sort key. If 'column' is not specified, one is assumed. For all other marks, the entire line is used as the sort key. In any case, all lines spanned by the mark are sorted, not just the text within the mark. One of the following options may be specified: d - sort in descending order i - ignore case when sorting returns: TRUE if successful, otherwise null. speaker [0/1] ────────────────────────────────────────────────────────────────────── remarks: Enables (1) or disables (0) sound from the PC speaker. returns: nothing see also: beep splitline col row buffer ────────────────────────────────────────────────────────────────────── remarks: Splits one line into two lines in a buffer. If 'buffer' is null or not specified, then the current buffer is assumed. 'row' specifies which line is to be split and 'col' specifies the column where the split is to occur. If 'row' and 'col' are not specified, the current cursor position is assumed. All characters after, and including the specified column are moved to column one in a new line after the line to be split. returns: TRUE if successful, otherwise null. see also: delline, insabove, insline, joinline example: splitline // splits the current line at the cursor in the // current buffer splitline 10 // splits the current line at column 10 splitstr delimit+quote multistring ref1 ref2 ... ────────────────────────────────────────────────────────────────────── remarks: Splits an editor 'multistring' (created by the 'joinstr' function) into individual strings. The 'delimit' and 'quote' characters are used as delimiters and literal quoting characters to separate the string (see 'joinstr' above). If 'delimit' and 'quote' are not specified, then the default delimiter character is a slash (/) and the default quote character is a backquote (`). 'ref1', 'ref2', etc. refer to variables passed by reference which are to contain the resulting component strings (see the 'ref' keyword). returns: This function returns the number of component strings in the multistring. The actual component strings are returned in variables passed by reference to this function. see also: joinstr, ref example: splitstr '' "abc/def/xyz" ref a ref b ref c // returns 'abc' in a, 'def' in b, and 'xyz' in c. // the entire function call returns '3' splitstr "|\\" "abc|x\|yz" ref a ref b // returns 'abc' in a, and 'x|yz' in b. // the entire function call returns '2' splitwin opt=[hv] [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Splits the current edit window. The following options may be specified: h - favor horizontal splits v - favor vertical splits returns: TRUE if successful, otherwise null. see also: copywin stopmark mark ────────────────────────────────────────────────────────────────────── remarks: Closes an 'open' mark created with the markline, markcolumn, markchar, or markstream functions. This stops the automatic extension of the mark when the cursor is moved. If 'mark' is not specified, the default markid is assumed. returns: nothing see also: extendmark, markchar, markcolumn, markline, markstream example: markline // marks the current line stopmark // stop cursor extension of the mark sub searchstr replacestr string opt=[irwx] ────────────────────────────────────────────────────────────────────── remarks: Replaces all occurrences of 'searchstr' found in 'string' with 'replacestr'. Any of the following search options may be specified: i - ignore case r - search in reverse from the end of the string w - whole words only x - use regular expressions (see Regexp.dox) Specifying a null replace string will remove all occurrences of 'searchstr' within 'string'. returns: The new string resulting from the substitution of 'replacestr' for all occurrences of the search string. see also: pos, poschar, posnot example: sub 'p' '112' "apples" // returns 'a112112les' sub 'es' 'y' "apples" // returns 'apply' sub 'PL' '' "apples" 'i' // returns 'apes' submenu menuname [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified menu as a submenu. This function is only intended for use within a pulldown menu. returns: nothing see also: getmenu, gotomenu, menu swapfiles swapfile1 swapfile2 swapfile3 ────────────────────────────────────────────────────────────────────── remarks: Defines swap files for the editor to use in low memory situations. If available, EMS and XMS memory will always be used before the swap files are created. 'swapfile2' will only be used when there is no room on the drive containing 'swapfile1', and 'swapfile3' will only be used when there is no room on the drive containing 'swapfile2'. All swap files should be on different drives. Note: this function may only be called once during an edit session. returns: TRUE if successful, otherwise null. see also: maxems, maxxms, memoptions syntax opt=[bcdfin] symbols1 symbols2 stringchars stringlit numeric eolcom1 startcol1 eolcom2 startcol2 opencom1 closecom1 opencom2 closecom2 backscan keywordcolor symbol1color symbol2color stringcolor numericcolor eolcomment1color eolcomment2color comment1color comment2color ────────────────────────────────────────────────────────────────────── remarks: Defines a syntax highlighting template for the current (executing) object. A syntax highlighting template can be customized to highlight the source code of almost any programming language, or even text files. Any of the following syntax highlighting options can be specified: b - highlighting shows through marked blocks c - enable highlighting for the cursor line d - enable highlighting for closed fold lines f - use only the foreground portion of the specified colors, and use the existing background color of the window i - ignore keyword case n - automatically highlight numbers The following parameters can also be specified: symbols1 - defines a set of 1-character symbols to be highlighted. A maximum of 40 symbols can be specified. symbols2 - defines an alternate set of 1-character symbols to be highlighted with a different color. A maximum of 40 symbols can be specified for symbols1 and symbols2 combined. stringchars - defines up to 3 one-character string symbols used to enclose highlighted character strings. stringlit - the character used to indicate a literal character in a character string. numeric - the character (if any) used to indicate a numeric value. eolcom1 - single line comment symbol 1 (10 char max) startcol1 - the required start column for 'eolcom1'. If not specified, all columns are checked. eolcom2 - single line comment symbol 2 (10 char max) startcol2 - the required start column for 'eolcom2'. If not specified, all columns all checked. opencom1 - the start symbol for multiline comment 1 (10 char max) closecom1 - the end symbol for multiline comment 1 (10 char max) opencom2 - the start symbol for multiline comment 2 (10 char max) closecom2 - the end symbol for multiline comment 2 (10 char max) backscan - the number of lines to scan backwards to check if a multiline comment is in effect (500 line max) The following syntax highlighting colors attributes may also be specified: keywordcolor stringcolor eolcom2color symbol1color numericcolor comment1color symbol2color eolcom1color comment2color If option 'f' is specified, and the window foreground color is equal to the foreground portion (lower 4 bits) of any of the above colors, then the background portions (upper 4 bits) of these colors are used as alternate foreground colors. This allows you to change the window color without having to change the syntax highlighting color definitions. returns: nothing see also: keyword, setsyntax example: see the configuration file Syntax.aml system program opt=[chk] ────────────────────────────────────────────────────────────────────── remarks: Executes a Dos program. Any of the following options may be specified: c - clears the screen before executing h - displays the header "Type EXIT to return" after executing the program k - prompts the user with a keypress to return to the editor Since the Dos 'PATH' is not searched, 'program' should be fully qualified or reside in the current directory. If the path of the program is not known, the function 'locatefile' can be used to search the Dos path. returns: the Dos errorlevel see also: delay, halt, locatefile tabblock (+/-)tabwidth[1-64] mark ────────────────────────────────────────────────────────────────────── remarks: Entabs or detabs marked text. If 'mark' is not specified, the default markid is assumed. 'tabwidth' specifies the tab width to use. If 'tabwidth' is not specified, then 8 is assumed. If 'tabwidth' is positive, then tab characters (Ascii 9) are converted into spaces (detab). If 'tabwidth' is negative, then spaces are converted into tab characters (entab). Spaces occurring on a line after a single quote, double quote, or tab character will not be entabbed. returns: TRUE if successful, otherwise null. thousands number ────────────────────────────────────────────────────────────────────── remarks: Converts a number into a thousands-separated string. The 'international' function determines what thousands separator character is used. returns: a thousands-separated string. see also: international example: thousands 12345678 // returns '12,345,678' tile opt=[hvlr] limit [Lib][win] ────────────────────────────────────────────────────────────────────── remarks: Tiles all non-minimized windows on the screen, and sets the maximize/restore title bar controls correctly for each window. See the 'tilewindow' function for a description of the options and the 'limit' argument. returns: nothing see also: cascade, splitwin, tilewindow tilewindow opt=[hvlb] limit splitnum window ────────────────────────────────────────────────────────────────────── remarks: Tiles windows on the screen, or 'splits' a window into tiles. If 'window' is not specified, the current window is assumed. 'limit' specifies the maximum number of tiles. If 'limit' is null or zero, then all windows are tiled. 'splitnum' specifies the maximum number of tiles that can be oriented in one direction before the next tile is oriented in a perpendicular direction. If 'splitnum' is null or zero, 2 is assumed. The following options can be specified: h - favors horizontal splits v - favors vertical splits l - tile only the specified window and any other windows which display the same buffer r - reverses the tiling order by starting with the nth window on the screen, where n='limit' If no options are specified, then 'h' is assumed. returns: TRUE if successful, otherwise null. see also: getcoord, movewindow, sizewindow example: tilewindow // tiles all windows horizontally on the screen tilewindow 'lv' // vertically tiles any windows which display // the same buffer as the current window timer? timerid ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified timer is active. returns: TRUE if timerid is active, otherwise null. see also: destroytimer, setalarm, settimer toolbar [Lib][edit] ────────────────────────────────────────────────────────────────────── remarks: Toggles the display of a toolbar on the current edit window. The toolbar is defined in Menu.aml. returns: nothing see also: togglestyle touchfile filename ────────────────────────────────────────────────────────────────────── remarks: Changes the last-modified date and time for the specified file to the current date and time. returns: Non-zero if successful, otherwise zero. see also: copyfile, setfileattr trackmouse [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor to the mouse pointer in the current buffer. returns: nothing see also: getmousex, getmousey, mousepos, virtocol, virtorow undo buffer ────────────────────────────────────────────────────────────────────── remarks: Reverses the changes made by the last undoable function (or group of functions marked with undobegin - undoend) for a specific buffer. If 'buffer' is null or not specified, then the current buffer is assumed. returns: TRUE if successful, otherwise null. see also: redo, undobegin, undoend undobegin ────────────────────────────────────────────────────────────────────── remarks: Marks the beginning of a group of function calls which are considered to be one undoable/redoable editing operation. The group is terminated by a matching 'undoend' function. 'undobegin' and 'undoend' pairs may be nested. Undo/redo information for all undoable function calls within this group is saved as one undoable operation on the undo/redo stack for each operation's buffer. The follow types of editing functions are undoable: - functions which modify buffers - functions which create or modify marks - functions which create or modify text folds The current cursor position, window size, and window view, are also saved on the undo/redo stack. When the 'undo' or 'redo' functions are called, all undoable editing operations within the group are 'undone' together at one time. returns: nothing see also: redo, undo, undocursor, undoend example: undobegin // groups 3 editing operations delline // together as one undoable writetext "some text" // operation insline "new line" undoend undocursor buffer ────────────────────────────────────────────────────────────────────── remarks: Saves the current window size, window view, and cursor position on the undo/redo stack as one undoable operation. If 'buffer' is null or not specified, then the current buffer is assumed. returns: nothing see also: redo, undo, undobegin, undoend undoend ────────────────────────────────────────────────────────────────────── remarks: Marks the end of a group of undoable/redoable function calls started with the 'undobegin' function (see 'undobegin' above). returns: nothing see also: redo, undo, undobegin undosize size buffer ────────────────────────────────────────────────────────────────────── remarks: Sets the undo/redo stack size for a buffer to 'size' editing operations. If 'buffer' is null or not specified, the current buffer is assumed. Setting the undo/redo stack size to zero disables undo/redo for the specified buffer. The stack size determines the maximum number of undoable editing operations (single or group) that will be saved for each buffer. When an undoable operation is performed and the size limit is exceeded, the undo information for the least-recently performed operation is discarded. When a buffer is initially created, the undo/redo stack size is set to zero (undo is disabled). Whenever the undo/redo stack size is changed with this function, all previous undo/redo information for the buffer is erased. returns: nothing see also: redo, undo, undobegin, undoend example: undosize // disables undo for the current buffer undosize 200 // deletes the current undo stack and sets the undo // stack size for the current buffer to 200 // editing operations up rows buffer ────────────────────────────────────────────────────────────────────── remarks: Moves the cursor upward. 'rows' specifies the number of lines to move. If 'rows' is not specified, then one is assumed. If 'buffer' is null or not specified, the current buffer is assumed. returns: the new cursor line number if successful, otherwise null. see also: down, left, right example: up // moves the cursor up 1 row up 5 // moves the cursor up 5 rows upcase string ────────────────────────────────────────────────────────────────────── remarks: Converts a string to uppercase. returns: the string in uppercase. see also: flipcase, locase example: upcase "peaches" // returns "PEACHES" usemark mark ────────────────────────────────────────────────────────────────────── remarks: Sets the default markid to 'mark'. If 'mark' is not specified, the markid '*' is assumed. When the editor is started, the default markid is '*'. returns: The previous default markid. see also: getmarkuse example: oldmark = usemark 'T' // set the default markid to 'T' : usemark oldmark // always restore the default markid variable? variable object ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified public variable exists in the object 'objectname'. If 'objectname' is not specified, the current object is assumed. Parent objects will also be checked. returns: TRUE if the variable exists, otherwise null. see also: function?, lookup videoborder color ────────────────────────────────────────────────────────────────────── remarks: Changes the video overscan border color to the specified color. returns: nothing videomode cols rows [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Changes the current video mode to 'cols' x 'rows'. 'cols' must be 40 or 80 and 'rows' must be 12, 14, 21, 25, 28, 43, or 50. returns: nothing see also: setvideo example: videomode 80 28 // change the video mode to 80 x 28 videomode 80 50 // change the video mode to 80 x 50 virtocol virtualX window ────────────────────────────────────────────────────────────────────── remarks: Converts a virtual screen X-coordinate to a column in a window. If 'window' is not specified, the current window is assumed. If 'virtualX' is not specified, the current mouse pointer position is assumed. returns: the window column. see also: virtorow example: say (virtocol) // displays the column in the current window where // the mouse pointer is located virtorow virtualY window ────────────────────────────────────────────────────────────────────── remarks: Converts a virtual screen Y-coordinate to a row in a window. If 'window' is not specified, the current window is assumed. If 'virtualY' is not specified, the current mouse pointer position is assumed. returns: the window row. see also: virtocol example: say (virtorow) // displays the row in the current window where // the mouse pointer is located whenenter functionn [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Defines an event-handling function to be called by the most recently defined dialog box control, when the control has the focus and the <enter> key (or equivalent) is pressed. The control 'id' (a number indicating the order in which the control was defined) is passed to the event-handling function. returns: nothing see also: dialog, getdialog, showdialog, whenselect example: dialog "Test Dialog Box" 40 8 button "&Test" 17 4 8 whenenter "testbutton" // beep when the 'Test' button is pressed function testbutton (id) msgbox "You pressed control #" + id end getdialog whenselect function [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Defines an event-handling function to be called by the most recently defined group box or list box control, when an item is selected within the control (without pressing <enter> or the equivalent). The function is also called when an edit field is updated from history. The control 'id' (a number indicating the order in which the control was defined) is passed to the event-handling function. returns: nothing see also: dialog, getdialog, showdialog, whenenter example: dialog "Test Dialog Box" 40 8 groupbox 'Radio Buttons: ' 10 2 ( menu '' item " ( ) Beep at &200hz" item " ( ) Beep at &400hz" item " ( ) Beep at &600hz" end ) whenselect "radio" function radio (id) beep getrow * 200 500 end getdialog window? window ────────────────────────────────────────────────────────────────────── remarks: Tests if a window exists. If 'window' is not specified, the current window is assumed. returns: TRUE if the window exists, otherwise null. see also: frame?, wintype? windowflag opt=[ds-] window ────────────────────────────────────────────────────────────────────── remarks: Turns window flags on or off, or tests if a window flag is turned on. If 'window' is null or not specified, the current window is assumed. The following flags can be specified: h - display the hex-view. The following additional flags can be specified: 1 - display the hardware cursor on the first hex character 2 - display the hardware cursor on the second hex character If flags 1 and 2 are off, the hardware cursor is displayed the in normal text portion of the window. p - send the <paint> event in the window event object after the window client area is updated. This allows custom drawing or highlighting of the window client area to be performed. s - send the <status> event in the window event object before the status line is updated. The return value of <status> will become the actual status line, allowing the status line to be customized. z - resizeable window - - turn specified flags off + - turn specified flags on ? - return true if specified flags are on If flags are specified without -, +, or ?, then they will be turned on and any other flags not specified will be turned off. returns: TRUE if '?' is specified with flags that are on, otherwise null winlist [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays a list of open windows. If a window is selected, it becomes the current window. returns: nothing see also: currwin wintype? object window ────────────────────────────────────────────────────────────────────── remarks: Tests if the specified object is located in the inheritance path of the window event object. If 'window' is not specified, the current window is assumed. returns: TRUE if 'object' is located in the inheritance path of the window event object, otherwise null. see also: objtype? example: wintype? "edit_fmgr" // tests if the object 'edit_fmgr' is located in the // inheritance path of the window (tests if the // window is a fmgr window or an edit window) write string [Ext][edit,prompt] ────────────────────────────────────────────────────────────────────── remarks: Enters a string into the current buffer at the cursor position, and moves the cursor to the end of the string. If the cursor is in insert mode, the string is inserted into the text, otherwise the string is overlaid onto the text. This function is similar to the 'writetext' function, but also provides support for the following window settings: - Hex View - Live Word Wrap - Match Character - Standard Word Wrap - Translate returns: nothing see also: instext, ovltext, writetext example: write "some text" writefile string opt=[k] handle ────────────────────────────────────────────────────────────────────── remarks: Writes the specified string at the current position in the open file specified by 'handle'. If a file handle is not specified, then the file handle returned from the most recent openfile call is assumed. The current position in the file is advanced by the number of characters written. If option 'k' is specified, the file date and time are not modified. returns: The number of characters written if successful, otherwise null. see also: closefile, filepos, openfile, readfile writeline string color col row ────────────────────────────────────────────────────────────────────── remarks: Displays the specified string in the current window using the color attribute 'color'. If 'col' and 'row' are not specified, the current cursor position is assumed. If 'color' is not specified, the window 'text' color is assumed (see 'setcolor'). The current cursor position is moved to column one of the next row. If the cursor was on the last row in the window, the window contents are scrolled up by one line. If the current window contains a buffer, the effects of this function (except for cursor movement) are temporary and will disappear the next time the display is updated. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, gotoxy, hilite, writestr example: writeline "some text" // writes the string 'some text' at the cursor and // moves the cursor to the next line writeline "some text" 95 // writes the string 'some text' at the cursor with the // color white on magenta, and moves the cursor to // the next line writestr string color col row ────────────────────────────────────────────────────────────────────── remarks: Displays the specified string in the current window using the color attribute 'color'. If 'col' and 'row' are not specified, the current cursor position is assumed. If 'color' is not specified, the window 'text' color is assumed (see 'setcolor'). The current cursor position is moved one column past the end of the string. If the current window contains a buffer, the effects of this function (except for cursor movement) are temporary and will disappear the next time the display is updated. returns: nothing see also: fillrect, getattr, getstr, getx, gety, gotoscreen, gotoxy, hilite, writeline example: writestr "some text" // writes the string 'some text' at the cursor writestr "some text" 95 // writes the string 'some text' at the cursor with the // color white on magenta writetext string col row buffer ────────────────────────────────────────────────────────────────────── remarks: Enters a string into a buffer at the specified row and column, and moves the cursor to the end of the string. If the cursor is in insert mode, then the text is inserted, otherwise the text is overlaid. If 'buffer' is null or not specified, then the current buffer is assumed. If 'col' and 'row' are not specified, then the string is inserted at the current cursor position. returns: TRUE if successful, otherwise null. see also: delchar, ovltext, write example: writetext "some text" // writes 'some text' at the cursor in the current // buffer writetext "some text" 2 20 // writes 'some text' at column 2, line 20 in the // current buffer writetext "some text" 1 1 "abc" // writes 'some text' at column 1, line 1 in the // buffer "abc" yncbox message title [Lib][a] ────────────────────────────────────────────────────────────────────── remarks: Displays the specified message in a popup window with 'Yes', 'No', and 'Cancel' buttons. If a title is not specified, 'Message' is assumed. returns: The name of the button pressed (Yes, No, or Cancel), or null if no button was pressed. see also: msgbox, okbox, say, shortbox example: yncbox "Replace the string?" "Replace" ┌─────────────────────────────────────────────────────────────────────┐ │ Builtin Events │ └─────────────────────────────────────────────────────────────────────┘ <compiling> filename linenumber ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor (A.exe) while a macro language source file is being compiled, and can be used to show progress during macro compilation. <compiling> is sent directly to the current event object and is passed the name of the file being compiled and the line number of the last line compiled. After the file is compiled, <compiling> is sent again with no arguments. returns: none required see also: <loading>, <printing>, <saving> example: see the configuration file Ext.aml <destroy> ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor (A.exe) to an object immediately before it is destroyed. It can be used to perform cleanup tasks in external macros, such as closing windows, setting flags, destroying buffers, timers, etc. returns: None required <display> ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor (A.exe) to the current event object immediately after the display is updated. see also: <paint>, <status> <loading> linenumber ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor (A.exe) as a file is being loaded, and can be used to show progress when loading a file. <loading> is sent directly to the current event object and is passed the line number of the last line loaded. After the file is loaded, <loading> is sent again with no arguments. returns: none required see also: <compiling>, <printing>, <saving> example: see the configuration file Ext.aml <paint> ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor (A.exe) immediately after a window client area is updated (the 'd' window flag must be turned on - see the 'windowflag' function). <paint> can be used to perform custom drawing or highlighting of the window client area. <paint> is called directly in the window event object with no arguments. Before calling this function, the editor sets the current window, current event object, and current buffer to those values associated with the window being drawn. returns: none required see also: <status>, windowflag <printing> linenumber ────────────────────────────────────────────────────────────────────── remarks: This event is called by the editor (A.exe) as a file is being printed, and can be used to show progress when printing a file. <printing> is sent directly to the current event object and is passed the line number of the last line printed. After the file is printed, <printing> is sent again with no arguments. returns: none required see also: <compiling>, <loading>, <saving> example: see the configuration file Ext.aml <saving> linenumber ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor (A.exe) as a file is being saved, and can be used to show progress when saving a file. <saving> is sent directly to the current event object and is passed the line number of the last line saved. After the file is saved, <saving> is sent again with no arguments. returns: none required see also: <compiling>, <loading>, <printing> example: see the configuration file Ext.aml <status> ────────────────────────────────────────────────────────────────────── remarks: This event is sent by the editor (A.exe) immediately before an edit window status line is updated (the 's' window flag must be turned on - see the 'windowflag' function). The return value of <status> will become the actual status line, allowing the status line to be customized. <status> is sent directly to the window event object with no arguments. Before calling this function, the editor sets the current window, current event object, and current buffer to those values associated with the window being drawn. returns: the new user-defined status line see also: <display>, <paint>, windowflag